1EdTech Revocation List Status Method

Candidate Final Public
Spec Version 1.0

Candidate Final Public

Document Version:	1.2
Date Issued:	April 5, 2024
Status:	This document is for review and adoption by the 1EdTech membership.
This version:	https://www.imsglobal.org/spec/vcrl/v1p0/main/
Latest version:	https://www.imsglobal.org/spec/vcrl/latest/main/
Errata:	https://www.imsglobal.org/spec/vcrl/v1p0/errata/

IPR and Distribution Notice

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

A simple list-based mechanism for publishing and checking the revocation status of a verifiable credential.

1. Introduction

A simple list-based mechanism for publishing and checking the revocation status of a verifiable credential.

This is a Status Method extension to Verifiable Credentials Data Model v2.0 and Verifiable Credentials Data Model v1.1. Using this extension, verifiers can determine if the issuer has revoked a credential.

1.1 Conformance Statements

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, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

2. Terminology

Issuer: The organization or entity that has made claims about a subject.
Verifiable Credential: A tamper-evident credential whose issuer can be cryptographically verified.
Verifier: The entity that receives a verifiable credential and verifies the credential or presentation has not been tampered with.

3. Protocol

If the issuer supports credential revocation, they SHOULD add a credentialStatus property to their issued credentials. The value of credentialStatus is a CredentialStatus object.

If the issuer supports this 1EdTech Revocation List Status Method, the id property of the CredentialStatus object MUST be the URL of the issuer's implementation. And the type property of the CredentialStatus object MUST be "1EdTechRevocationList".

To check if a credential has been revoked, the verifier issues a GET request to the URL of the issuer's 1EdTech Revocation List Status Method. If the credential's id is in the list of revokedCredentials and the value of revoked is true or ommitted, the issuer has revoked the credential.

All requests MUST be made over secure TLS 1.2 or 1.3 protocol.

Example 1: Sample usage of the Revocation List

{
  "id": "http://example.edu/credentials/3732",
  "type": ["Credential", "DegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "issuanceDate": "2010-01-01T19:73:24Z",
  "credentialSubject": { ... }
  "credentialStatus": {
    "id": "https://example.edu/revocations/24,
    "type": "1EdTechRevocationList"
  },
  "proof": { ... }
}

Request Format

GET {id}

URL Parameter	Parameter Type	Description	Required
`id`	URI	The HTTP scheme (which MUST be "https"), domain name, and any other path elements required by the issuer (e.g. "https://example.edu/revocations/24"). The URL is opaque to the verifier.	Required

Request Headers

Request Header	Description	Required
`Accept: application/json`	If the content type `application/json` is not not included in the `Accept` header, the issuer MAY respond with 406 Not Acceptable.	Required

Request Payload

There is no request payload.

Sample Request

Example 2: Sample request

GET revocations/24 HTTP/1.1
Host: example.edu
Accept: application/json

Responses

HTTP Status Code	Payload Type	Description	Payload Required
200	RevocationList	'OK' - The credential revocation list.	Required
400	Imsx_StatusInfo	'Bad Request' - The request was invalid or cannot be served. The exact error should be explained in the response payload.	Required

Response Headers

Response Header	Description	Required
`Content-Type: application/json`	The content type MUST be `application/json`.	Required

Sample Response

Example 3: Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "https://example.edu/revocations/24",
  "issuer": "https://example.edu/issuers/14",
  "revokedCredentials": [{
    "id": "http://example.edu/credentials/3732",
    "revoked": "true",
    "revocationReason": "No final payment"
  }]
}

4. Data Model

4.1 RevocationList

Property	Type	Description	Multiplicity
id	`URI`	The `id` of the revocation list.	[1]
issuer	`URI`	The `id` of the issuer.	[1..*]
revokedCredential	`RevokedCredential`	The credentials that have been revoked by the issuer. Issuers may include previously revoked credentials that have been re-instated, setting `revoked` to false.	[0..*]

4.2 RevokedCredential

Property	Type	Description	Multiplicity
id	`URI`	The `id` of the revoked credential.	[1]
revoked	`Boolean`	True if the credential is revoked. Defaults to `true` and may be ommitted.	[0..1]
revocationReason	`String`	The published reason for revocation if desired.	[0..1]

4.3 CredentialStatus

The information in CredentialStatus is used to discover information about the current status of a verifiable credential, such as whether it is suspended or revoked.

Property	Type	Description	Multiplicity
id	`URI`	The value MUST be the URL of the issuer's credential status method.	[1]
type	`IRI`	The name of the credential status method.	[1]

4.4 Imsx_StatusInfo

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.

Property	Type	Description	Multiplicity
imsx_codeMajor	`Imsx_CodeMajor Enumeration`	The code major value (from the corresponding enumerated vocabulary).	[1]
imsx_severity	`Imsx_Severity Enumeration`	The severity value (from the corresponding enumerated vocabulary).	[1]
imsx_description	`String`	A human readable description supplied by the entity creating the status code information.	[0..1]
imsx_codeMinor	`Imsx_CodeMinor`	The set of reported code minor status codes.	[0..1]

4.5 Imsx_CodeMajor Enumeration

This is the set of primary status report values i.e. the major code assigned to the status block. This is used in conjunction with the 'Severity' structure in the status object.

Term	Description
failure	Denotes that the transaction request has failed. The detailed reason will be reported in the accompanying 'codeMinor' fields.
processing	Denotes that the request is being processed at the destination or there has been a local transmission failure. This value is used in asynchronous services.
success	Denotes that the request has been successfully completed. If the associated 'severity' value is 'warning' then the request has been partially successful i.e. best effort by the service provider. Other parts of the status information may provide more insight into a partial success response.
unsupported	Denotes that the service provider does not support the requested operation. This is the required default response for an unsupported operation by an implementation.

4.6 Imsx_Severity Enumeration

This is the context for the status report values. This is used in conjunction with the 'CodeMajor' structure in the status object.

Term	Description
error	A catastrophic error has occurred in processing the request and so the request was not completed (the Service Provider may not even have received the request).
status	The request has been completed and a response was received from the Service Provider.
warning	The request has only been partially completed. For an asynchronous service a further response should be expected.

4.7 Imsx_CodeMinor

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

Property	Type	Description	Multiplicity
imsx_codeMinorField	`Imsx_CodeMinorField`	Each reported code minor status code.	[1..*]

4.8 Imsx_CodeMinorField

This is the container for a single code minor status code.

Property	Type	Description	Multiplicity
imsx_codeMinorFieldName	`NormalizedString`	This should contain the identity of the system that has produced the code minor status code report.	[1]
imsx_codeMinorFieldValue	`Imsx_CodeMinorFieldValue Enumeration`	The code minor status code (this is a value from the corresponding enumerated vocabulary).	[1]

4.9 Imsx_CodeMinorFieldValue Enumeration

This is the set of codeMinor status codes that are used to provide further insight into the completion status of the end-to-end transaction i.e. this should be used to provide more information than would be supplied by an HTTP code.

Term	Description
forbidden	This is used to indicate that the server can be reached and process the request but refuses to take any further action. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '403'.
fullsuccess	The request has been fully and successfully implemented by the service provider. For a REST binding this will have an HTTP code of '200' for a successful search request.
internal_server_error	This should be used only if there is catastrophic error and there is not a more appropriate code. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '500'.
invalid_data	This error condition may occur if a JSON request/response body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and a HTTP code of '422'.
invalid_query_parameter	An invalid data query parameter field was supplied and the query could not be processed. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '400'.
misdirected_request	This is used to indicate that the request was made with a protocol that is not supported by the server. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '421'.
not_acceptable	This is used to indicate that the server cannot provide a response with a Content-Type that matches any of the content types in the request Accept header. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '406'.
not_allowed	This is used to indicate that the server does not allow the HTTP method. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '405'.
not_modified	This is used to indicate that the server did not modify the resource. This would be accompanied by the 'codeMajor/severity' values of 'success/status' and for a REST binding a HTTP code of '304'.
server_busy	The server is receiving too many requests. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '429'.
unauthorizedrequest	The request was not correctly authorised. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '401'.
unknown	Any other error occurred. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code corresponding to the error.

5. Derived Types

Type	Description
IRI	A `NormalizedString` that represents an Internationalized Resource Identifier (IRI), which extends the ASCII characters subset of the Uniform Resource Identifier (URI).
Term	A term in an enumeration. The lexical constraints are the same as for `Token`.
URI	A `NormalizedString` that respresents a Uniform Resource Identifier (URI).

6. Primitive Types

Type	Description
Boolean	A boolean, expressed as `true` or `false`
NormalizedString	A `String` conforming to the `normalizedString` definition in [XMLSCHEMA-2].
String	Character strings.

A. Revision History

Status	Doc Version	Release Date	Comments
Candidate Final Public	1.0	June 8, 2022
Candidate Final Public	1.1	May 18, 2023	Rename `revokedCredentials` property to `revokedCredential`, keeping the naming convention used in the vc-data-model and in the CLR 2 and OB 3 data models.
Candidate Final Public	1.2	April 5, 2024	Updated to Verifiable Credentials Data Model v2.0

B. References

B.1 Normative references

[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
[VC-DATA-MODEL]: Verifiable Credentials Data Model v1.1. Manu Sporny; Grant Noble; Dave Longley; Daniel Burnett; Brent Zundel; Kyle Den Hartog. W3C. 3 March 2022. W3C Recommendation. URL: https://www.w3.org/TR/vc-data-model/
[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/
[XMLSCHEMA-2]: XML Schema Part 2: Datatypes Second Edition. Paul V. Biron; Ashok Malhotra. W3C. 28 October 2004. W3C Recommendation. URL: https://www.w3.org/TR/xmlschema-2/

C. List of Contributors

The following individuals contributed to the development of this document:

Name	Organization	Role
Andy Miller	1EdTech	Author
Xavi Aracil	1EdTech	Editor

You are here