1EdTech Verifiable Credential Refresh Service

1EdTech Verifiable Credential Refresh Service

Candidate Final Public
Spec Version 1.0
Candidate Final Public
Document Version: 1.1
Date Issued: April 5, 2024
Status: This document is for review and adoption by the 1EdTech membership.
This version: https://www.imsglobal.org/spec/vccr/v1p0/main/
Latest version: https://www.imsglobal.org/spec/vccr/latest/main/
Errata: https://www.imsglobal.org/spec/vccr/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 .

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

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

Abstract

A manual method to refresh an expired or modified verifiable credential.

1. Introduction

A manual method to refresh an expired or modified verifiable credential.

This is a Verifiable Credentials Refresh Service extension to Verifiable Credentials Data Model v2.0 and Verifiable Credentials Data Model v1.1. Using this extension, verifiers can manually refresh an expired or modified verifiable 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 refresh, they SHOULD add a refreshService property to their issued credentials. The value of the refreshService property is a list of one or more RefreshService objects.

If the issuer supports this 1EdTech Credential Refresh Service, the id property of one RefreshService object MUST be the URL of the issuer's implementation. And the type property of the RefreshService object MUST be "1EdTechCredentialRefresh".

To manually refresh a credential, the verifier issues a GET request to the URL of the issuer's 1EdTech Credential Refresh Service. The issuer will respond with a refreshed verifiable credential.

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

Example 1: Sample usage of the 1EdTech Credential Refresh Service 
{
  "id": "http://example.edu/credentials/3732",
  "type": ["Credential", "DegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "credentialSubject": { ... }
  "refreshService": [{
    "id": "https://example.edu/refresh/3732,
    "type": "1EdTechCredentialRefresh"
  }],
  "proof": { ... }
}

Request Format

GET {id}

URL Parameter Parameter Type Description Required
id URI This is value of the id property of the RefreshService object. The HTTP scheme MUST be "https" and the request MUST be made over secure TLS 1.2 or 1.3 protocol. Required

Request Headers

Request Header Description Required
Accept: application/json, application/ld+json, application/vc+ld+json, text/plain The request SHOULD accept all 4 content types. Required
Line breaks in headers added for clarity

Request Payload

There is no request payload.

Sample Request

Example 2: Sample request 
GET refresh/3732 HTTP/1.1
Host: example.edu
Accept: application/json, application/vc+ld+json, application/ld+json, text/plain

Responses

HTTP Status Code Content-Type Header Payload Type Payload Description Payload Required
200 application/json or application/ld+json or application/vc+ld+json VerifiableCredential The refreshed verifiable credential. If the verifiable credential was not signed with a VC-JWT proof, the payload will be a serialized VerifiableCredential. Required
200 text/plain CompactJws The refreshed verifiable credential. If the verifiable credential was signed with a VC-JWT proof, the payload will be a CompactJws. Required
default application/json Imsx_StatusInfo The request was invalid or cannot be served. The exact error should be explained in the response payload. Optional

Sample Response

Example 3: Sample response with extended expiration date 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "http://example.edu/credentials/3732",
  "type": ["Credential", "DegreeCredential"],
  "issuer": "https://example.edu/issuers/14",
  "credentialSubject": { ... }
  "refreshService": [{
    "id": "https://example.edu/refresh/3732,
    "type": "1EdTechCredentialRefresh"
  }],
  "proof": { ... }
}

4. Data Model

4.1 RefreshService

The information in RefreshService is used to refresh the verifiable credential.

Property Type Description Multiplicity
id URI The value MUST be the URL of the issuer's refresh service. [1]
type IRI The name of the refresh service method. [1]
This class can be extended with additional properties.

4.2 VerifiableCredential

A Verifiable Credential as defined in either [VC-DATA-MODEL-2.0] or [VC-DATA-MODEL].

Property Type Description Multiplicity
@context URI The value of the @context property MUST be an ordered set where the first item is a URI with the value 'https://www.w3.org/ns/credentials/v2', as defined by [VC-DATA-MODEL-2.0], or 'https://www.w3.org/2018/credentials/v1', as defined by [VC-DATA-MODEL]. [1..*]
id URI Unambiguous reference to the credential. [0..1]
type IRI The value of the type property MUST be an unordered set. One of the items MUST be the URI 'VerifiableCredential'. [1..*]
issuer Issuer A description of the individual, entity, or organization that issued the credential. [1]
credentialSubject CredentialSubject The subject of the credential. [1]
refreshService RefreshService One or more RefreshServices that provide enough information to the recipient's software such that the recipient can refresh the verifiable credential. [0..*]
This class can be extended with additional properties.

4.3 CredentialSubject

Information about the subject of the verifiable credential.

Property Type Description Multiplicity
id URI The id of the subject. [1]
This class can be extended with additional properties.

4.4 Issuer

Information about the verifiable credential issuer.

Property Type Description Multiplicity
id URI The id of the issuer. [1]
This class can be extended with additional properties.

4.5 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.6 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.7 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.8 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.9 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.10 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
CompactJws A String in Compact JWS format [RFC7515].
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
DateTime An [ISO8601] time using the syntax YYYY-MM-DDThh:mm:ss.
Namespace A namespace data type for defining data from a context other than that as the default for the data model. This is used for importing other data models.
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 April 5, 2024 Updated to Verifiable Credentials Data Model v2.0

B. References

B.1 Normative references

[ISO8601]
Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[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
[RFC7515]
JSON Web Signature (JWS). M. Jones; J. Bradley; N. Sakimura. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7515
[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 Miller1EdTechAuthor
Xavi Aracil1EdTechEditor

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 Verifiable Credential Refresh Service 1.0

Date: April 5, 2024