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.
Status of This Document
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/.
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.
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.
1.1 Conceptual Framework
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.
Figure 1
A visual depiction of the concepts outlined in this section.
1.2 Terminology
This section is non-normative.
The following terms are used to describe concepts in this specification.
The act of limiting the amount of shared data strictly to the minimum
necessary to successfully accomplish a task or goal.
decentralized identifier
A portable URL-based identifier, also known as a DID,
associated with an entity. These identifiers are most often used in a
verifiable credential and are associated with subjects such that a
verifiable credential itself can be easily ported from one
repository to another without the need to reissue the credential.
An example of a DID is did:example:123456abcdef.
Anything that can be referenced in statements as an abstract or concrete noun.
Entities include but are not limited to people, organizations, physical things,
documents, abstract concepts, fictional characters, and arbitrary text. Any
entity might perform roles in the ecosystem, if it is capable of doing so. Note
that some entities fundamentally cannot take actions, e.g., the string "abc"
cannot issue credentials.
graph
A set of claims, forming a network of information composed of subjects
and their relationship to other subjects or data. Each claim is
part of a graph; this is either explicit in the case of named graphs, or
implicit for the default graph.
An identity provider, sometimes abbreviated as IdP, is a system
for creating, maintaining, and managing identity information for
holders, while providing authentication services to
relying party applications within a federation or distributed network.
In this case the holder is always the subject. Even if the
verifiable credentials are bearer credentials, it is assumed the
verifiable credentials remain with the subject, and if they are
not, they were stolen by an attacker. This specification does not use this term
unless comparing or mapping the concepts in this document to other
specifications. This specification decouples the identity provider
concept into two distinct concepts: the issuer and the holder.
A graph associated with specific properties, such as
verifiableCredential or proof. These properties
result in separate graphs that contain all claims defined in the
corresponding JSON objects.
A verifiable credential is a tamper-evident credential that has authorship that
can be cryptographically verified. Verifiable credentials can be used to build
verifiable presentations, which can also be cryptographically verified.
verifiable data registry
A role a system might perform by mediating the creation and verification
of identifiers, keys, and other relevant data, such as
verifiable credential schemas, revocation registries, issuer public keys,
and so on, which might be required to use verifiable credentials. Some
configurations might require correlatable identifiers for subjects. Some
registries, such as ones for UUIDs and public keys, might just act as namespaces
for identifiers.
verifiable presentation
A verifiable presentation is a tamper-evident presentation encoded in such a way
that authorship of the data can be trusted after a process of cryptographic
verification. Certain types of verifiable presentations might contain data that
is synthesized from, but do not contain, the original verifiable credentials
(for example, zero-knowledge proofs).
verification
The evaluation of whether a verifiable credential or verifiable
presentation is an authentic and current statement of the issuer or
presenter, respectively. This includes checking that: the credential (or
presentation) conforms to the specification; the proof method is satisfied; and,
if present, the status check succeeds. Verification of a credential does not
imply evaluation of the truth of claims encoded in the credential.
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.
2. Data Model
The following sections outlines the data model for this document.
2.1 BitstringStatusListEntry
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:
Value
Description
revocation
Used to cancel the validity of a verifiable credential. This status is
not reversible.
suspension
Used to temporarily prevent the acceptance of a verifiable credential.
This status is reversible.
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 credentialMUST have type property that
includes the BitstringStatusListCredential value.
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:
Value
Description
revocation
Used to cancel the validity of a verifiable credential. This status is
not reversible.
suspension
Used to temporarily prevent the acceptance of a verifiable credential.
This status is reversible.
status
Used to indicate a status message associated with a verifiable
credential. The status message descriptions MUST be defined in
credentialSubject.statusMessages. credentialSubject.sizeMUST be defined
with this statusPurpose.
credentialSubject.encodedList
The encodedList property of the credential subjectMUST 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
6.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. sizeMAY be
provided. If size is not present as a property of the credentialStatus, then
sizeMUST be processed as 1. sizeMUST be an integer greater than zero.
If size is provided and is greater than 1, then the property
credentialStatus.statusMessagesMUST 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. statusMessagesMAY be present if
size is 1. statusMessagesMUST 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:
status, being a string of the hex value of the status
value, being a string containing the associated message
Implementers MAY add additional values to objects in the 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
reference is especially important when interpretation of the status for a
credential may involve some understanding of the business case involved.
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.
Let status purpose be the value of statusPurpose
in the credentialStatus entry in the
credentialToValidate.
Dereference the 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.
Verify that the status purpose matches the
statusPurpose value in the statusListCredential.
Let status be the value at the position indicated by the
credentialIndex times the size in the bitstring.
For 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.
3.3 Bitstring Generation Algorithm
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.
Let bitstring be a list of bits with a minimum size of 16KB,
where each bit is initialized to 0 (zero).
For each value in 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.
Generate a compressed bitstring by using the GZIP
compression algorithm [RFC1952] on the bitstring
and then base64-encoding [RFC4648] the result.
Return the compressed bitstring.
3.4 Bitstring Expansion Algorithm
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.
Let compressed bitstring be a compressed status list
bitstring.
Generate an uncompressed bitstring by using the
base64-decoding [RFC4648] algorithm on the
compressed bitstring and then expanding the output using
the GZIP decompression algorithm [RFC1952].
Return the uncompressed bitstring.
4. Media Types
This section is non-normative.
When dereferencing statusListCredential, the content type of the
statusListCredential might be any media type registered for the purpose of
expressing a verifiable credential with one or more proofs.
For example, a verifiable credential secured with Data Integrity Proofs might
have content type application/vc+ld+json, whereas a verifiable credential
secured with SD-JWT might have content-type application/sd-jwt.
Some implementations might choose to support less specific media types such as
application/ld+json or application/json.
When dereferencing over HTTP, the use of the accept
and content-type headers, might allow
some implementations to negotiate for the proof format used to secure the
statusListCredential.
Some implementations might use the 415
Unsupported Media Type status code to signal that they do not support the
requested media type.
5. Privacy Considerations
This section is non-normative.
This section details the general privacy considerations and specific privacy
implications of deploying this specification into production environments.
5.1 Revocation Bitstring Length
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.
5.2 Verifier Caching
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.
5.3 Content Distribution Networks
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.
5.4 Malicious Issuers and Verifiers
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.
6. Security Considerations
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.
6.1 Bitstring Encoding
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.
Figure 2
A visual depiction of the bitstring layout.
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.
Implementations SHOULD consume and/or assign indexes randomly.
7. Accessibility 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.
Issue
Write accessibility considerations.
8. Internationalization 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.
