Bitstring Status List v1.0

Privacy-preserving status information for Verifiable Credentials

W3C Working Draft

More details about this document
This version:
https://www.w3.org/TR/2024/WD-vc-bitstring-status-list-20240406/
Latest published version:
https://www.w3.org/TR/vc-bitstring-status-list/
Latest editor's draft:
https://w3c.github.io/vc-bitstring-status-list/
History:
https://www.w3.org/standards/history/vc-bitstring-status-list/
Commit history
Editors:
Manu Sporny (Digital Bazaar)
Dave Longley (Digital Bazaar)
Mike Prorock (mesur.io)
Mahmoud Alkhraishi (Mavennet)
Authors:
Dave Longley (Digital Bazaar)
Manu Sporny (Digital Bazaar)
Orie Steele (Transmute)
Feedback:
GitHub w3c/vc-bitstring-status-list (pull requests, new issue, open issues)
Related Documents
Verifiable Credentials Data Model

Abstract

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/.

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.

1. Introduction

This section is non-normative.

It is often useful for an issuer of verifiable credentials [VC-DATA-MODEL-2.0] 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 group 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 group 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 specification. At the most basic level, status information for all verifiable credentials issued by an issuer is expressed as items in a list. Each issuer manages a list of all verifiable credentials that it has issued. Each verifiable credential is associated with an item in its list. When a single bit specifies a status, such as "revoked" or "suspended", then that status is expected to be true when the bit is set (1) and false when unset (0).

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 status list size is 131,072 entries, equivalent to 16 KB of single bit values. When only a handful of verifiable credentials are revoked, GZIP compresses the bitstring 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 uses a minimum list length of 131,072. This size ensures an adequate amount of group privacy in the average case. If better group privacy is required, the bitstring can be made larger.

diagram showing a
               list of boxes at the top of the image with two of them in
               red depicting revoked credentials. Text beside the boxes to the
               right reads 16 kilobytes. An depiction of the boxes being
               GZIP compressed into a cylinder on the bottom of the page shows
               that compression has resulted in a final size of 135 bytes.
Figure 1 A visual depiction of the concepts outlined in this section.
Note: Status information is about the verifiable credential

The status information associated with a particular verifiable credential is about the verifiable credential itself and might not apply to any underlying or backing credential, such as an educational degree. For example, in the case of such an educational degree, it is possible for a verifiable credential to be revoked because the mechanism used to create its digital signature has been compromised, while the backing educational degree remains valid.

1.2 Terminology

This section is non-normative.

The following terms are used to describe concepts in this specification.

claim
An assertion made about a subject.
credential
A set of one or more claims made by an issuer. The claims in a credential can be about different subjects.

Our definition of credential differs from, NIST's definitions of credential.

data minimization
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.
decentralized identifier document
Also referred to as a DID document, this is a document that is accessible using a verifiable data registry and contains information related to a specific decentralized identifier, such as the associated repository and public key information.
default graph
The graph containing all claims that are not explicitly part of a named graph.
derived predicate
A verifiable, boolean assertion about the value of another attribute in a verifiable credential. These are useful in zero-knowledge-proof-style verifiable presentations because they can limit information disclosure. For example, if a verifiable credential contains an attribute for expressing a specific height in centimeters, a derived predicate might reference the height attribute in the verifiable credential demonstrating that the issuer attests to a height value meeting the minimum height requirement, without actually disclosing the specific height value. For example, the subject is taller than 150 centimeters.
digital signature
A mathematical scheme for demonstrating the authenticity of a digital message.
entity
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.
holder
A role an entity might perform by possessing one or more verifiable credentials and generating verifiable presentations from them. A holder is often, but not always, a subject of the verifiable credentials they are holding. Holders store their credentials in credential repositories.
identity
The means for keeping track of entities across contexts. Digital identities enable tracking and customization of entity interactions across digital contexts, typically using identifiers and attributes. Unintended distribution or use of identity information can compromise privacy. Collection and use of such information should follow the principle of data minimization.
identity provider
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.
issuer
A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder.
named graph
A graph associated with specific properties, such as verifiableCredential. These properties result in separate graphs that contain all claims defined in the corresponding JSON objects.
presentation
Data derived from one or more verifiable credentials, issued by one or more issuers, that is shared with a specific verifier.
repository
A program, such as a storage vault or personal verifiable credential wallet, that stores and protects access to holders' verifiable credentials.
selective disclosure
The ability of a holder to make fine-grained decisions about what information to share.
subject
A thing about which claims are made.
user agent
A program, such as a browser or other Web client, that mediates the communication between holders, issuers, and verifiers.
validation
The assurance that a claim from a specific issuer satisfies the business requirements of a verifier for a particular use. This specification defines how verifiers verify verifiable credentials and verifiable presentations.
It also specifies that verifiers validate claims in verifiable credentials before relying on them. However, the means for such validation vary widely and are outside the scope of this specification. It is expected that verifiers will trust certain issuers for certain claims and apply their own rules to determine which claims in which credentials are suitable for use by their systems.
verifiable credential
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.
verifier
A role an entity performs by receiving one or more verifiable credentials, optionally inside a verifiable presentation for processing. Other specifications might refer to this concept as a relying party.
verification material
Information that could be a cryptographic public key or any other data used to verify a proof.
URL
A Uniform Resource Locator, as defined by [URL]. URLs can be dereferenced such that they result in a resource, such as a document. The rules for dereferencing, or fetching, a URL are defined by the URL scheme. This specification does not use the term URI or IRI because those terms have been deemed to be confusing to Web developers.

1.3 Conformance

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, SHOULD, and SHOULD 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.

A conforming document is any concrete expression of the data model that follows the relevant normative requirements in Section 2. Data Model.

A conforming processor is any algorithm realized as software and/or hardware that generates and/or consumes a conforming document according to the relevant normative statements in Section 3. Algorithms. Conforming processors MAY choose to only support bitstring entry sizes of 1. Conforming processors MUST produce errors when non-conforming documents are consumed.

2. Data Model

There are numerous ways to express status information associated with digital credentials. Some of these mechanisms include Certificate Revocation Lists (CRL) [RFC5280], the Online Certificate Status Protocol (OCSP) [RFC2560], Bloom Filters [RFC8932], and cryptographic accumulators [ALLOSAUR]. This specification optimizes for a variety of requirements that are different from other mechanisms. These requirements include:

Technology CRL OCSP Bloom Accumulator Bitstring
Provides tunable group privacy
Does not require signed assertion for each credential
Resistant to issuer tracking when fetched by verifier
Caching is space efficient with many revocations
Highly compressible (>90% average compression)
Updates are efficient (fast and entire population does not need to update)
Uses cryptographic primitives approved by IETF
No false positives
Can be delivered by holder (stapling)
Easily profiled for usage with verifiable credentials

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 section. Any expression of the data model in this section MUST be expressed in a conforming verifiable credential as defined in [VC-DATA-MODEL-2.0].

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-2.0]. 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.
message Used to convey an arbitrary message related to the status of the verifiable credential.
statusListIndex The statusListIndex property MUST be an arbitrary size integer greater than or equal to 0, expressed as a string in base 10. The value identifies the position of the status of the verifiable credential. Implementations SHOULD assign indexes randomly, such that inferences — such as the recency of the assignment or the size of the group — cannot be easily drawn from that position.
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.
Example 1: Example StatusListCredential
{
  "@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"
  }
}

2.2 BitstringStatusListCredential

When a status list verifiable credential is published, it MUST be a conforming document, as defined in [VC-DATA-MODEL-2.0], that expresses the data model in this section. The following section describes the format of the verifiable credential that encapsulates the status list:

(Feature at Risk) Issue 1: Bitstring entry sizes greater than 1 are at risk.

The Working Group is currently seeking implementer feedback regarding the utility of bitstring entries that have sizes greater than one. Supporting such entries adds complexity to the solution, and it's not clear whether there is enough of an implementation community to support the feature. The WG is considering three options: (1) require conforming implementations to support the feature; (2) allow implementations to optionally support the feature; or (3) remove the feature. At present, the specification implements option (2).

(Feature at Risk) Issue 2: TTL conflicts with `validUntil`

The Working Group is considering the removal of the ttl ("time to live") feature because its semantics conflict with the semantics of the validUntil feature of verifiable credentials. When a verifier performs validation and evaluates a BitstringStatusListCredential that contains both a ttl property and a validUntil property, each with a different value (i.e., each indicating a different point in time when the credential is to "expire"), it is not clear which (if either) property a validator can be expected to ignore. In other words, if a ttl value specifies an expiration datetime of midnight today, but the validUntil property specifies an expiration datetime of midnight tomorrow, then what is a verifier expected to do? Fundamentally, ttl and validUntil have conflicting semantics. One way to resolve this conflict is to remove ttl and specify that caching behavior can be expressed using protocol mechanisms (such as the expires header in HTTP), and that any caching performed MUST align with the validUntil value for the verifiable credential. The Working Group is seeking feedback from the implementer community regarding this feature.

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 value of the purpose property of the status entry, statusPurpose, MUST be one or more strings. While the value of each 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.
message Used to indicate a status message associated with a verifiable credential. The status message descriptions MUST be defined in credentialSubject.statusMessages. credentialSubject.statusSize MUST be specified when this statusPurpose value is used.
credentialSubject.encodedList The encodedList property of the credential subject MUST be a Multibase-encoded base64url (with no padding) [RFC4648] representation of the GZIP-compressed [RFC1952] 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.statusSize The statusSize indicates the size of the status entry in bits. statusSize MAY be provided. If statusSize is not present as a property of the credentialStatus, then statusSize MUST be processed as 1. statusSize MUST be an integer greater than zero. If statusSize is provided and is greater than 1, then the property credentialStatus.statusMessage MUST be present, and the number of status messages must equal the number of possible values.
credentialSubject.statusMessage The statusMessage property MUST be an array. If present, the length of the array must equal the number of possible status states indicated by statusSize. statusMessages MAY be present if statusSize is 1. statusMessages MUST be present if statusSize 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 statusMessage array MUST contain at minimum two properties:
  • status, a string representing the hexadecimal value of the status prefixed with 0x
  • message, a string used by software developers to assist with debugging which SHOULD NOT be displayed to end users.
Implementers MAY add additional values to objects in the statusMessage 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.statusReference The statusReference property provides a point for implementers to include a [URL] to material related to the status. An implementer MAY include the statusReference 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 statusReference.
Note: Details around reference

statusReference is especially important when interpretation of the status for a credential may involve some understanding of the business case involved.

The example below demonstrates how the BitstringStatusListEntry is used with a BitstringStatusListCredential to provide the verifier with the information necessary to determine the status of a particular verifiable credential.

Example 2: Example BitstringStatusListCredential
{
  "@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": "uH4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
  }
}

The status list is expressed inside a verifiable credential in order to enable a holder to provide it to a verifier directly. This mechanism, sometimes called "certificate stapling", increases privacy for the holder by ensuring that the verifier does not need to contact the issuer to retrieve the status list. Still, a verifier might choose to ignore the holder-provided status list, even when its authenticity is verifiable, if it desires a more recent version of a status list, for instance.

Example 3: Example BitstringStatusListCredential
{
  "@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",
    "statusReference": "https://example.org/status-dictionary/",
    "statusSize": 2,
    "statusMessage": [
        {"status":"0x0", "message":"valid"},
        {"status":"0x1", "message":"invalid"},
        {"status":"0x2", "message":"pending_review"},
        ...
    ],
    "encodedList": "uH4sIAAAAAAAAA-3BMQEAAADAAAAAAAAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
  }
}

Issuers and verifiers are advised that the issuer of a verifiable credential and the issuer of an associated BitstringStatusListCredential might not be the same. There are technical, legal, institutional, and political reasons that might make it appropriate to separate the authority over the original credential from the authority to revoke such a credential. Therefore, the issuer value of a verifiable credential containing a BitstringStatusListEntry MAY be different from the issuer value of a BitstringStatusListCredential.

3. Algorithms

The following section outlines the algorithms that are used to generate and validate status lists as described by this document.

If an implementation of any of the algorithms in this section processes a property defined in Section 2. Data Model whose value is malformed due to not complying with associated "MUST" statements, a MALFORMED_VALUE_ERROR MUST be raised.

(Feature at Risk) Issue 3: Attempting alignment with IETF Token Status List specification

The Working Group is seeking feedback related to implementer desire to align with the IETF OAuth Working Group Token Status List specification (formerly titled OAuth Status List, and JWT and CWT Status List). If there is interest, and to the extent possible, this specification might align more closely with the Token Status List bitstring format, as it could be beneficial to have one code base able to process bitstring values from both lists. If there is implementer support for such changes, they might be made during the Candidate Recommendation phase.

3.1 Generate Algorithm

The following process, or one generating the exact output, MUST be followed when producing a BitstringStatusListCredential. The algorithm takes a list of issued credentials as input and either throws an error or returns a status list credential as output.

  1. Let issued credentials be a list of all issued verifiable credentials.
  2. Let statusListCredential be an unsigned BitstringStatusListCredential without the encodedList property set.
  3. Generate a compressed bitstring by passing issued credentials to the Bitstring Generation Algorithm.
  4. Set the encodedList to compressed bitstring.
  5. Generate a proof for the statusListCredential and publish it to the endpoint listed in the verifiable credential.

Issuers SHOULD publish status list credentials in a way that can be cached and that does not track who retrieves the status list credential, such as through Oblivious HTTP, a content distribution network that is not operated by the issuer, or business processes for which the access logs are not accessible by data analysts or systems administrators.

3.2 Validate Algorithm

The following process, or one generating the exact output, MUST be followed when validating a verifiable credential that is contained in a BitstringStatusListCredential. The algorithm takes a status list verifiable credential as input and either throws an error or returns a status list credential as output.

  1. Let credentialToValidate be a verifiable credential containing a credentialStatus entry that is a BitstringStatusListEntry.
  2. Let minimumNumberOfEntries be 131,072 unless a different lower bound is established by a specific ecosystem specification.
  3. Let status purpose be the value of statusPurpose in the credentialStatus entry in the credentialToValidate.
  4. Dereference the statusListCredential URL, and ensure that all proofs verify successfully. If the dereference fails, raise a STATUS_RETRIEVAL_ERROR. If any of the proof verifications fail, raise a STATUS_VERIFICATION_ERROR.
  5. Verify that the status purpose is equal to a statusPurpose value in the statusListCredential. Note: The statusListCredential might contain multiple status purposes in a single list. If the values are not equal, raise a STATUS_VERIFICATION_ERROR.
  6. Let compressed bitstring be the value of the encodedList property of the BitstringStatusListCredential.
  7. Let credentialIndex be the value of the statusListIndex property of the BitstringStatusListEntry.
  8. Generate a revocation bitstring by passing compressed bitstring to the Bitstring Expansion Algorithm.
  9. If the length of the revocation bitstring divided by statusSize is less than minimumNumberOfEntries, raise a STATUS_LIST_LENGTH_ERROR.
  10. Let status be the value in the bitstring at the position indicated by the credentialIndex multiplied by the size. If the credentialIndex multiplied by the size is a value outside of the range of the bitstring, a RANGE_ERROR MUST be raised.
  11. Let result be an empty map.
  12. Set the status key in result to status, and set the purpose key in result to the value of statusPurpose.
  13. If status is 0, set the valid key in result to true; otherwise, set it to false.
  14. If the statusPurpose is message, set the message key in result to the corresponding message of the value as indicated in the statusMessages array.
  15. Return result.

When a statusListCredential URL is dereferenced, server implementations MAY provide a mechanism to dereference the status list as of a particular point in time. When an issuer provides such a mechanism, it enables a verifier to determine changes in status to a precision chosen by the issuer, such as hourly, daily, or weekly. If such a feature is supported, and if query parameters are supported by the URL scheme, then the name of the query parameter MUST be timestamp and the value MUST be a valid URL-encoded [XMLSCHEMA11-2] dateTimeStamp string value. The result of dereferencing such a timestamp-parameterized URL MUST be either a status list credential containing the status list as it existed at the given point in time, or a STATUS_RETRIEVAL_ERROR. If the result is an error, implementations MAY attempt the retrieval again with a different timestamp value, or without a timestamp value, as long as the verifier's validation rules permit such an action.

Verifiers SHOULD cache the retrieved status list and SHOULD use proxies or other mechanisms, such as Oblivious HTTP, that hide retrieval behavior from the issuer.

Note: Issuer validation is use case dependent

It is expected that a verifier will ensure that it trusts the issuer of a verifiable credential, as well as the issuer of the associated BitstringStatusListCredential, before using the information contained in either credential for further decision making purposes. Implementers are advised that the issuers of these credential might differ, such as when the original issuer of the verifiable credential does not maintain a record of its validity.

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 an issuedCredentials list as input and either throws an error or returns a compressed bitstring as output.

  1. Let bitstring be a list of bits with a minimum size of 16KB, where each bit is initialized to 0 (zero).
  2. 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 statusSize.
  3. Generate a compressed bitstring by using the GZIP compression algorithm [RFC1952] on the bitstring and then base64url-encoding (with no padding) [RFC4648] the result.
  4. 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 either throws an error or returns a uncompressed bitstring as output.

  1. Let compressed bitstring be a compressed status list bitstring.
  2. Generate an uncompressed bitstring by using the base64url-decoding (with no padding) [RFC4648] algorithm on the compressed bitstring and then expanding the output using the GZIP decompression algorithm [RFC1952].
  3. Return the uncompressed bitstring.

3.5 Processing Errors

The algorithms described in this specification throw specific types of errors. Implementers might find it useful to convey these errors to other libraries or software systems. This section provides specific URLs, descriptions, and error codes for the errors, such that an ecosystem implementing technologies described by this specification might interoperate more effectively when errors occur.

When exposing these errors through an HTTP interface, implementers SHOULD use Problem Details for HTTP APIs [RFC9457] to encode the error data structure. If [RFC9457] is used:

STATUS_RETRIEVAL_ERROR (-128)
Retrieval of the status list failed. See Section 3.2 Validate Algorithm.
STATUS_VERIFICATION_ERROR (-129)
Validation of the status entry failed. See Section 3.2 Validate Algorithm.
STATUS_LIST_LENGTH_ERROR (-130)
The status list length does not satisfy the minimum length required for herd privacy. See Section 3.2 Validate Algorithm.

3.6 Securing Algorithms

There are multiple ways that the information in Section 2. Data Model can be secured. These mechanisms are elaborated upon in the Securing Mechanisms section of the Verifiable Credentials Data Model v2.0.

When securing a verifiable credential that contains a reference to a BitstringStatusListCredential, implementers SHOULD use the same securing mechanism with the same cryptographic parameters and the same media type for both verifiable credentials.

4. Media Types

When dereferencing statusListCredential, the content of the returned 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 media type application/vc+ld+json, while a verifiable credential secured with SD-JWT might have media 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.

Readers are urged to familiarize themselves with the general privacy advice provided in the Privacy Considerations section of the Verifiable Credentials specification before reading this section.

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 group 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 Unnecessary Correlation

This section is non-normative.

There are a number of global identifiers used in a status list entry, defined in Section 2.1 BitstringStatusListEntry, that can be used across verifiers to correlate subjects. Some of the properties that can express these values are id, statusListIndex, and statusListCredential.

In some cases, such as when presenting a verifiable credential that contains any other global identifier (such as a driver's license identification number), adding one or more global identifier(s) for the status list information does not increase correlation harm, since a single globally unique identifier is all that is required for correlation.

When global identifiers are used in presentations that use selective disclosure or unlinkable disclosure, they can violate privacy expectations. Issuers are urged to enable status information to be selectively disclosable/concealable when a particular verifiable credential is expected to be disclosed in a way that does not need correlation, such as when proving that an individual is above a certain age. Verifiers can require that status information be revealed in situations that require them to know the current status of a credential, and the holder might then consent or refuse to reveal that information for a given transaction. In all cases, both issuers and verifiers are urged to avoid the use of global identifiers in order to prevent correlation, unless it is required for or by a particular exchange.

For information on other types of potential correlation, readers are urged to study the Privacy Considerations section of the Verifiable Credentials Data Model v2.0 specification, particularly the subsections on Identifier-Based Correlation, Signature-Based Correlation, Long-Lived Identifier-Based Correlation, and Metadata-Based Correlation.

5.3 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.4 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.5 Decoy Values

This section is non-normative.

Issuer use of decoy values in status lists has been explored as a mechanism to increase the privacy of subjects. While algorithms for employing decoy values are out of scope for this specification, implementers are advised that the use of decoy values do not provide privacy gains and can harm privacy in most cases.

When status list entry indexes are allocated in a random fashion, which is the suggested mode of operation for this specification, adding decoys harms privacy because it reduces the group privacy size by the number of decoys added to the group. A random allocation of indexes inherently hides the true group size, ensuring that decoys are not necessary.

There might be use cases where decoy values provide benefits. Implementers are cautioned that no such use cases were clearly identified by the group that created this specification. As a result, the use of decoys is discouraged for most use cases, as random allocation of status list entry indexes provides adequate protection.

5.6 Malicious Issuers and Verifiers

This section is non-normative.

In general, the group 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 group privacy by creating a unique status list per credential issued in order to establish a one-to-one mapping to track when a verifier processes a specific credential. Similarly, they could establish another a one-to-one mapping by using a different cryptographic key for every credential issued that is tracked in a status list.

A malicious verifier might intentionally attack group privacy by sharing information from presented credentials with a malicious issuer.

5.7 Monitoring Status Lists

This section is non-normative.

Once a verifier knows of a status list and entry index that is associated with a specific holder or subject, it becomes possible for that verifier to see updates to that status entry as long as the status list continues to be updated. This is useful to a verifier that needs to understand when a particular verifiable credential has changed status without asking the issuer directly for status information on the specific verifiable credential or when interacting with the holder to get the latest status information is not possible. The feature can also cause a privacy violation for the holder and/or subject if the verifier is able to perform near-real-time checks on the status of the verifiable credential.

Issuers can provide a level of reprieve from this privacy concern holders by revoking and reissuing effectively the same verifiable credential on a timeline that is relatively short in nature. For example, an issuer could automatically reissue a verifiable credential every three months and assign a new status entry index when the reissuance occurs to break any sort of long-term monitoring of a verifiable credential as it changes status.

5.8 Correlation of Status Messages

This section is non-normative.

This specification provides a means by which multiple status messages can be provided for a particular entry in a status list. While this mechanism can provide more detailed information for a particular entry in the status list, that information can provide further correlation data.

For example, if each status message is associated with a step in a particular process, or more detailed information as to why a credential was revoked or suspended, then an attacker that observes the changes in the list might be able to correlate information about the population of entities in the list that could lead to privacy violations. Understanding how a population progresses through a business process, or what percentage of the population is likely to be associated with a certain status, provides additional information to an attacker. Given such information, a phishing operation could predict what the next step of a business process is and then preemptively contact an entity whose current status is known. Then, based on that information, they could attempt to phish more lucrative information from the target using data gleaned from the status list over time.

For these reasons, issuers are urged to evaluate the potential ramifications of publishing detailed status information about a particular entity, or a population, in a public manner.

5.9 Alteration of Status Messages

This section is non-normative.

When a status list uses the status messages feature, it becomes possible for the issuer to increase the types of messages that are associated with the verifiable credentials it issues over time.

This feature creates a potential privacy violation where the subject or holder of the verifiable credential might be associated with additional status information that was not present when the original verifiable credential was issued. For example, initial status messages might convey "delayed" and "canceled", but additional status messages might be added by the issuer to convey "delayed due to non-payment" and "canceled due to illegal activity". This change would not be apparent to the subject or holder unless there was monitoring software operating on their behalf that would warn them that the issuer intends to expose additional information about their activity.

Holder software can provide features to holders that warn them about the level of holder and/or subject information exposure when using verifiable credentials that are associated with status messages, and warn them when the level of information exposure changes.

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.

Readers are urged to familiarize themselves with the general security advice provided in the Security Considerations section of the Verifiable Credentials specification before reading this section.

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.

a diagram showing two
             wide rectangles shown side-by-side. Each rectangle is partitioned
             into eight boxes to represent the 8 bits in a byte. The left
             rectangle is labeled 'First byte' and the right rectangle is
             labeled 'Last byte'. The left rectangle's left-most bit box is
             pointed to by an arrow labeled 'index: 0'. The right rectangle's
             right-most bit box is pointed to by an arrow labeled
             'index: length - 1'.
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.

7. Accessibility Considerations

This section is non-normative.

Readers are urged to familiarize themselves with the general accessibility advice provided in the Accessibility Considerations section of the Verifiable Credentials specification. No further advice is provided in this specification beyond the general advice for all verifiable credentials.

8. Internationalization Considerations

This section is non-normative.

Readers are urged to familiarize themselves with the general internationalization advice provided in the Internationalization Considerations section of the Verifiable Credentials specification. No further advice is provided in this specification beyond the general advice for all verifiable credentials.

9. Appendix

This section is non-normative.

9.1 Examples

9.1.1 Revocable Verifiable Credential

Example 4: A Revocable Verifiable Credential
Verifiable CredentialSecured with Data IntegritySecured with VC-JWT
{
  "@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"
  }
}

9.1.2 Status List Verifiable Credential

Example 5: A Status List Verifiable Credential
Verifiable CredentialSecured with Data IntegritySecured with VC-JWT
{
  "@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": "uH4sIAAAAAAAAA-3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAIC3AYbSVKsAQAAA"
  }
}

9.1.3 Multiple Status Lists in One Verifiable Credential

This specification enables an issuer to associate multiple status lists with a single verifiable credential.

Example 6: Associating multiple status lists with a single Verifiable Credential
{
  "@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",
  "issuanceDate": "2021-04-05T14:27:42Z",
  // note the use of an array to represent the set of
  // status entries
  "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#12345",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "suspension",
    "statusListIndex": "12345",
    "statusListCredential": "https://example.com/credentials/status/4"
  }],
  "credentialSubject": {
    "id": "did:example:6789",
    "type": "Person"
  }
}

9.1.4 Multiple Status Entries in a Single List

It is possible for a single status list to contain multiple types of status purposes. Doing so can make the retrieval of a list slightly more efficient than fetching multiple status lists.

(Feature at Risk) Issue 4: Efficiency argument is weak

The "space efficiency" argument for this feature is weak. One list with two types of status entries must, presumably, be twice as long as a list with one type of status entries, to ensure proper privacy protections. One privacy benefit of doing so is that bit flips cannot be known to be associated with a particular status unless one is also in control of the VC that the status is about. Therefore, mixing "revocation" and "suspension" in a single list that is twice as large has positive privacy implications.

The "retrieval efficiency" argument is also weak. Performing two HTTP retrievals instead of one is probably not significant. Performing upwards of five or six, on a list that is five or six times larger, might result in fairly meager savings over modern versions of HTTP that bundle requests over a single channel (such as HTTP/2 or HTTP/3). The requests themselves would save a handful of bytes with no significant improvement in retrieval speed.

The Working Group is looking for feedback from implementers and is considering striking this feature during the Candidate Recommendation period, since it would simplify the specification for implementations to not have to support sets of statusPurpose values in the status list credentials (again, a meager savings in space efficiency at a small cost to retrieval efficiency).

Example 7: Associating multiple status entries in a single status list
{
  "@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",
  "issuanceDate": "2021-04-05T14:27:42Z",
  // note the use of a single list to store multiple
  // status entries
  "credentialStatus": [{
    "id": "https://example.com/credentials/status/5#94567",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "revocation",
    "statusListIndex": "94567",
    "statusListCredential": "https://example.com/credentials/status/5"
  }, {
    "id": "https://example.com/credentials/status/5#12345",
    "type": "BitstringStatusListEntry",
    "statusPurpose": "suspension",
    "statusListIndex": "12345",
    "statusListCredential": "https://example.com/credentials/status/5"
  }],
  "credentialSubject": {
    "id": "did:example:6789",
    "type": "Person"
  }
}

A. References

A.1 Normative references

[infra]
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC1952]
GZIP file format specification version 4.3. P. Deutsch. IETF. May 1996. Informational. URL: https://www.rfc-editor.org/rfc/rfc1952
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC4648]
The Base16, Base32, and Base64 Data Encodings. S. Josefsson. IETF. October 2006. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4648
[rfc7231]
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC9457]
Problem Details for HTTP APIs. M. Nottingham; E. Wilde; S. Dalal. IETF. July 2023. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9457
[RFC9458]
Oblivious HTTP. M. Thomson; C. A. Wood. IETF. January 2024. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc9458
[URL]
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[VC-DATA-INTEGRITY]
Verifiable Credential Data Integrity 1.0. Manu Sporny; Dave Longley; Greg Bernstein; Dmitri Zagidulin; Sebastian Crane. W3C. 15 March 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-data-integrity/
[VC-DATA-MODEL-2.0]
Verifiable Credentials Data Model v2.0. Manu Sporny; Ted Thibodeau Jr; Ivan Herman; Michael Jones; Gabe Cohen. W3C. 2 April 2024. W3C Candidate Recommendation. URL: https://www.w3.org/TR/vc-data-model-2.0/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. David Peterson; Sandy Gao; Ashok Malhotra; Michael Sperberg-McQueen; Henry Thompson; Paul V. Biron et al. W3C. 5 April 2012. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema11-2/

A.2 Informative references

[ALLOSAUR]
ALLOSAUR: Accumulator with Low-Latency Oblivious Sublinear Anonymous credential Updates with Revocations. Cryptology ePrint Archive. January 5th, 2024. URL: https://eprint.iacr.org/2022/1362.pdf
[RFC2560]
X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP. M. Myers; R. Ankney; A. Malpani; S. Galperin; C. Adams. IETF. June 1999. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc2560
[RFC5280]
Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile. D. Cooper; S. Santesson; S. Farrell; S. Boeyen; R. Housley; W. Polk. IETF. May 2008. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc5280
[RFC8932]
Recommendations for DNS Privacy Service Operators. S. Dickinson; B. Overeinder; R. van Rijswijk-Deij; A. Mankin. IETF. October 2020. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8932