MediatedRefreshService2021 Protocol

The MediatedRefreshService2021 protocol is used when an issuer uses a refresh prodedure that is non-automatable or requires an interactive exchange with the holder. The manual refresh protocol consists of executing the following steps:

1. The holder software extracts the `refreshService.type`, `refreshService.url`, and `refreshService.validFrom` properties and saves them as type, url, and validFrom, respectively.
2. If type does not equal `MediatedRefreshService2021`, raise an `INVALID_REFRESH_ALGORITHM` exception.
3. If validFrom is defined, but expresses a datetime that is later than the current datetime, raise a `REFRESH_NOT_ALLOWED` exception.
4. If url is not defined, raise an `INVALID_URL` exception.
5. Open an application, such as a Web browser, that is capable of handling url and pass the value to be opened to the application.

The example below demonstrates what an HTTP client would perform after the final step above:

GET /refresh/3732 HTTP/1.1
Host: example.edu
Accept: text/html, */*
Accept-Encoding: gzip, deflate
      

VerifiableCredentialRefreshService2021 Protocol

The VerifiableCredentialRefreshService2021 protocol is used when an issuer uses a refresh prodedure that does not require an interactive exchange with the holder and is therefore, fully automatable. The auto refresh protocol consists of executing the following steps:

1. The holder software extracts the `refreshService.type`, `refreshService.url`, `refreshService.validFrom`, and `refreshService.validUntil` properties and saves them as type, url, validFrom, and validUntil, respectively.
2. If type does not equal `VerifiableCredentialRefreshService2021`, raise an `INVALID_REFRESH_ALGORITHM` exception.
3. If validFrom is defined, but expresses a datetime that is later than the current datetime, raise a `REFRESH_NOT_ALLOWED` exception.
4. If validUntil is defined, but expresses a datetime that is before the current datetime, raise a `REFRESH_NOT_ALLOWED` exception.
5. If url is not defined, raise an `INVALID_URL` exception.
6. Use an HTTP client to perform an HTTP GET on url. The response from the server MUST be a Verifiable Presentation Request [[VP-REQUEST]] as defined by the Presenting section of the [[VC-API]] specification.

The following examples elaborate upon the flow of messages after the final step above is executed:

GET /workflows/refresh-degree HTTP/1.1
Host: example.edu
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate
      

HTTP/1.1 200 OK
Date: Fri, 14 Jun 2022 18:37:12 GMT
Connection: keep-alive

{
  "verifiablePresentationRequest": {
    "query": [{
        "type": "DIDAuth"
      }, {
        "type": "QueryByExample",
        "credentialQuery": {
          "reason": "We need to see your existing University Degree credential.",
          "example": {
            "@context": [
              "https://www.w3.org/2018/credentials/v1",
              "https://www.w3.org/2018/credentials/examples/v1"
            ],
            "type": "UniversityDegreeCredential"
          }
        }
      }],
      "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
      "domain": "example.edu",
      "interact": {
        "service": [{
          "type": "VerifiableCredentialRefreshService2021",
          "serviceEndpoint": "https://example.edu/active-flows/123456"
        }]
      }
    }
  }
}
      

While the example above utilizes a Verifiable Presentation Request [VP-REQUEST], other types of equivalent presentation request formats, such as WACI/PeX, can be utilized (simultaneously or alternatively) based on the presentation request formats that are supported by the Issuer.

POST /active-flows/123456 HTTP/1.1
Host: example.edu
Content-Type: application/json
Accept: application/json, */*
Accept-Encoding: gzip, deflate

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1",
    "https://w3id.org/security/suites/ed25519-2020/v1"
  ],
  "type": ["VerifiablePresentation"],
  "holder": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "verifiableCredential": [{
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "http://example.edu/credentials/3732",
    "type": [
      "VerifiableCredential",
      "UniversityDegreeCredential"
    ],
    "issuer": "https://example.edu/issuers/14",
    "issuanceDate": "2010-01-01T19:23:24Z",
    "expirationDate": "2022-01-01T19:23:24Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "refreshService": {
      "type": "VerifiableCredentialRefreshService2021",
      "url": "https://example.edu/workflows/refresh-degree",
      "validFrom": "2021-09-01T19:23:24Z"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2021-12-05T17:59:45Z",
      "verificationMethod": "https://example.edu/issuers/14#key-1",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                     ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
    }
  }],
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2022-06-15T16:37:12Z",
    "verificationMethod": "did:example:76e12ec712ebc6f1c221ebfeb1f#key-1",
    "proofPurpose": "authentication",
    "challenge": "3182bdea-63d9-11ea-b6de-3b7c1404d57f",
    "domain": "example.edu",
    "proofValue": "z4aU6NSpnCvnjJqzAPw3cqJ1LKoWimEWxKz7StJYzwaZE2a3QAuK8vcq
                   umwr6uabr7RshvjH1yTv1fTuhPUii1fN"
  }
}
      

HTTP/1.1 200 OK
Date: Fri, 14 Jun 2022 18:37:12 GMT
Connection: keep-alive

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "type": ["VerifiablePresentation"],
  "verifiableCredential": [{
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1",
      "https://w3id.org/security/suites/ed25519-2020/v1"
    ],
    "id": "http://example.edu/credentials/3732",
    "type": [
      "VerifiableCredential",
      "UniversityDegreeCredential"
    ],
    "issuer": "https://example.edu/issuers/14",
    "issuanceDate": "2010-01-01T19:23:24Z",
    "expirationDate": "2027-06-14T18:37:12Z",
    "credentialSubject": {
      "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
      "degree": {
        "type": "BachelorDegree",
        "name": "Bachelor of Science and Arts"
      }
    },
    "refreshService": {
      "type": "VerifiableCredentialRefreshService2021",
      "url": "https://example.edu/workflows/refresh-degree",
      "validFrom": "2027-03-14T19:23:24Z",
      "validUntil": "2027-07-14T19:23:24Z"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2022-06-14T18:37:12Z",
      "verificationMethod": "https://example.edu/issuers/14#key-1",
      "proofPurpose": "assertionMethod",
      "proofValue": "z2aArNcQKX9aqYK7GRZmV7c9xfGuwB5YAXhkYY9DTvLdTCQEsXaNpz1G
                     ZL9XDXdFQGT27WB68e2Y3wo9k75rka8oo"
    }
  }]
}