1EdTech Revocation List Status Method

1EdTech Revocation List Status Method

Candidate Final Public
Spec Version 1.0
Candidate Final Public
Document Version: 1.1
Date Issued: May 18, 2023
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 .

© 2023 1EdTech™ Consortium, Inc. All Rights Reserved.

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

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/
[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 Miller1EdTechAuthor

1EdTech™ Consortium, Inc. ("1EdTech") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

1EdTech makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

1EdTech would appreciate receiving your comments and suggestions.

Please contact 1EdTech through our website at www.1edtech.org.

Please refer to Document Name: 1EdTech Revocation List Status Method 1.0

Date: May 18, 2023