This specification describes a mechanism for publishing the revocation status of Verifiable Credentials that leverages directory service (e.g. Active Directory), where respective records are publicly accessible via LDAP.

This document is experimental and is undergoing heavy development. It is inadvisable to implement the specification in its current form. An experimental implementation is available.

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

Introduction

In the majority of cases, businesses already implement some known revocation approaches.

One of these "known" options is the usage of directory services such as Active Directory that provides the access to records via Lightweight Directory Access Protocol (LDAP).

An issuer of verifiable credentials in such a system [[VC-DATA-MODEL]] can use a pointer to a particular location at directory service inside of verifiable credential, that a verifier can check to see if a credential has been revoked.

The Data Model section covers each vocabulary item, its properties, other attributes for each item.

Terminology

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

Process Flow

Here we describe the assumptions in this usage of an underlying directory service, which leverages LDAP to obtain records of revocation status for a given verifiable credential.

First of all, entire verifiable credentials issued by an issuer are not assumed to be recorded in directory service by default. Some subset of information, however, need to be retained for revocation to be executed later, i.e. the pointer to where a revocation record will be posted if that credential is revoked later. This record can contain more or less information, but it is assumed this record at least exist to claim credential status as revoked.

In the case of a given credential's revocation, a respective record becomes publicly accessible and a data of this record can be returned via an LDAP URL that can be be securely and deterministically constructed via the following list of properties of a verifiable credential: If a record is returned by the query assembled from these variables, thereafter, this verifiable credential should be considered as revoked and any additional information will be included in the returned message.

Data Model

The following sections outlines the data model for this document.

You may view the latest json-ld vocabulary at:
https://spherity.github.io/vc-status-2021-ldap/contexts/vc-status-2021-ldap/v1.jsonld

RevocationStatus2021LDAP

When an issuer desires to enable revocation for a verifiable credential, they MAY add a status property that uses the data model described in this specification.

Term RevocationStatus2021LDAP
Full IRI https://spherity.github.io/vc-status-2021-ldap#RevocationStatus2021LDAP 
            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1"
              ],
              "id": "https://example.com/credentials/23894672367",
              "type": ["VerifiableCredential"],
              "issuer": "did:example:12345",
              "issued": "2021-01-11T00:35:00Z",
              "credentialStatus": {
                "id": "ldaps://62.242.203.212:636/o=dolor,cn=ipsum,ou=lorem,dc=example,dc=com",
                "type": "RevocationStatus2021LDAP",
                "ssl": true,
                "host": "62.242.203.212:636",
                "query": "o={{0}},cn={{1}},ou={{2}},dc={{3}},dc={{4}}",
                "params": [
                  "dolor",
                  "ipsum",
                  "lorem",
                  "example",
                  "com"
                ]
              },
              "credentialSubject": {
                "id": "did:example:6789",
                "type": "Person"
              },
              "proof": { ... }
            }
          
            {
              "@context": [
                "https://www.w3.org/2018/credentials/v1"
              ],
              "id": "https://example.com/credentials/23894672367",
              "type": ["VerifiableCredential"],
              "issuer": "did:example:12345",
              "issued": "2021-01-11T00:35:00Z",
              "credentialStatus": {
                "id": "ldaps://example.com/o=dolor,cn=ipsum,ou=lorem,dc=example,dc=com",
                "type": "RevocationStatus2021LDAP",
                "ssl": true,
                "host": "example.com",
                "query": "o={{0}},cn={{1}},ou={{2}},dc={{3}},dc={{4}}",
                "params": [
                  "dolor",
                  "ipsum",
                  "lorem",
                  "example",
                  "com"
                ]
              },
              "credentialSubject": {
                "id": "did:example:6789",
                "type": "Person"
              },
              "proof": { ... }
            }

SSL

The ssl property MUST be a boolean value if present or it MAY be skipped that should be treated the same as like false value was provided. In case true value is provided then ldaps protocol will be applied, otherwise - ldap.

Term ssl
Full IRI https://spherity.github.io/vc-status-2021-ldap#ssl

Host

The host property MUST be a valid domain address, or host ip address with port address concatenated using :.

Term host
Full IRI https://spherity.github.io/vc-status-2021-ldap#host

Query

The query property MUST a be a valid LDAP search query for the verifiable credential revocation status location. Numbers that are present inside brackets identify indexes of respective values from credentialStatus.params params array.

Term query
Full IRI https://spherity.github.io/vc-status-2021-ldap#query

Params

The params property MUST be input params for credentialStatus.params query.

Term params
Full IRI https://spherity.github.io/vc-status-2021-ldap#params

Algorithms

The following section outlines the algorithms that are used to initialize, revoke and validate revocation status as described by this document.

Initialization Algorithm

This process MUST be followed to define LDAP URL parts for identifying a location for a potential revocation status record per each verifiable credential that includes RevocationStatus2021LDAP method as value for its credentialStatus.type property, and thus relies on an underlying directory service to store revocation information.

  1. Define parts of LDAP URL to a resource at directory service that MAY resolve to an array of results to describe the revocation status for the verifiable credential in question. LDAP URL parts MUST include following properties ssl, host, query and params.
  2. Securely combine aforementioned LDAP URL parts to construct a fully qualified LDAP URL value and apply its value to credentialStatus.id property.
  3. Apply aforementioned LDAP URL parts as values to respective properties within credentialStatus section.

Revocation Algorithm

This process MUST be followed to execute revocation per each verifiable credential that includes RevocationStatus2021LDAP method as value for its credentialStatus.type property, and thus relies on an underlying directory service to store revocation information.

  1. Create a revocation status record at the location defined by LDAP URL parts described inside credentialStatus section of a given verifiable credential. The record MAY include a description property. The record MAY also include a date property. The value of the date property MUST be ISO string or UNIX timestamp in milliseconds. ISO string format is suggested due to its readability.

Validation Algorithm

This process MUST be followed to identify revocation status of verifiable credential that includes RevocationStatus2021LDAP method as value for its credentialStatus.type property. This identifies it as relying on underlying LDAP directory service.

  1. Build a fully qualified LDAP URL by securely combining properties from credentialStatus section of a verifiable credential.
  2. Execute LDAP search operation using LDAP URL.
  3. Evaluate results of LDAP search operation.

    In case error code 32 (not found) is thrown, then the status of a verifiable credential should be considered as not rovoked.

    In case LDAP search operation results are recieved, then the status of a verifiable credential should be considered as revoked.

    If present, LDAP search results MAY include an object with description property. If present, description property MUST be a string.

    If present, LDAP search results MAY include an object with date property. If present, date property MUST be a date as ISO-formatted string or UNIX Epoch milliseconds as number.

Privacy Considerations

This section details the general privacy considerations and specific privacy implications of deploying this specification into production environments.

Correlation

This method is best suited for fully public or semi-public credentials; potentially leaking status information is assumed to be an acceptable risk, and recent, signed data about current status of a verifiable credential is assumed to be "authoritative" over other or older records, which this method is not optimized to minimize.

Referencing the verifiable credential's unique ID in the LDAP query string adds additional correlation risk, which may be an anti-pattern in some use cases.

Security Considerations

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.

Our architecture assumes keys are managed in common across both issuance and status-publication infrastructure. The latter is assumed to be secured by LDAPS; LDAP-specific security is assumed and largely out of scope of this specification, although LDAP queries are stored in the credential in both composed and decomposed form to assure validation and comparison to better secure queries.

Further research would be needed on how (or whether it is worthwhile) to sign the specific status object and how to verify the relationship between signing key of same and issuance key of original VC. A signed envelope around the status object returned (or even a fully-formed credential issued against a published schema) is definitely one possibility, for use-cases where metadata passed along with status would be complex, or need to be secured additionally.

Accessibility Considerations

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.

Internationalization Considerations

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.