Verifiable Credentials (VCs)

A verifiable credential, or VC, is a means for an issuer to issue a credential stating a fact about a subject in a cryptographically secure, tamper-proof, and machine-readable and -verifiable way. In the context of evan.network, VCs allow to use the verification mechanism in a global scope, interoperable with other blockchains.
The essential parts of a VC are:

• the IDs of both the issuer and the subject, which are DIDs, each pointing to a DID document containing cryptographical material used for authentication and verification
• credential data, that contains payload that makes up the statement of the credential, and
• a cryptographical proof, that ensures
  • the integrity of the VC since the proof becomes invalid as soon as a detail about the VC is changed, and
  • the legitimacy of the VC. Only the issuer of the VC can create a valid proof signature, because only he knows his private key. The proof can easily be verified using the issuer’s DID, which holds the related public key.

Sample VC

A typical VC in evan.network might look like this:

{
 "@context": [ "https://www.w3.org/2018/credentials/v1" ],
  "type": [ "VerifiableCredential" ],
  "id": "vc:evan:testcore:0x6e90a3e2bf3823e52eceb0f81373eb58b1a0a238965f0d4388ab9ce9ceeddfd3",  
  "issuer": {
    "id": "did:evan:testcore:0x96da854df34f5dcd25793b75e170b3d8c63a95ad" 
  },
  "credentialSubject": {
    "id": "did:evan:testcore:0x67ce8b01b3b75a9ba4a1462139a1edaa0d2f539f",
    "data": [
      {
        "name": "isTrustedSupplier",
        "value": "true"
      }
    ] 
  },
  "validFrom": "2020-02-25T09:48:57.660Z",
  "credentialStatus": {
    "id": "https://testcore.evan.network/vc/status/vc:evan:testcore:0x6e90a3e2bf3823e52eceb0f81373eb58b1a0a238965f0d4388ab9ce9ceeddfd3",
    "type": "evan:evanCredential" 
  },
  "proof": { 
    "type": "EcdsaPublicKeySecp256k1",
    "created": "2020-02-25T09:48:58.451Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:evan:testcore:0x96da854df34f5dcd25793b75e170b3d8c63a95ad#key-1",
    "jws": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NkstUiJ9.eyJpYXQiOjE1ODI2MjQxMzgsInZjIjp7IkBjb250ZXh0IjpbImh0dHBzOi8vd3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiXSwiaXNzdWVyIjp7ImlkIjoiZGlkOmV2YW46dGVzdGNvcmU6MHg5NmRhODU0ZGYzNGY1ZGNkMjU3OTNiNzVlMTcwYjNkOGM2M2E5NWFkIn0sImNyZWRlbnRpYWxTdWJqZWN0Ijp7ImlkIjoiZGlkOmV2YW46dGVzdGNvcmU6MHg2N2NlOGIwMWIzYjc1YTliYTRhMTQ2MjEzOWExZWRhYTBkMmY1MzlmIiwiZGF0YSI6W3sibmFtZSI6ImlzVHJ1c3RlZFN1cHBsaWVyIiwidmFsdWUiOiJ0cnVlIn1dfSwidmFsaWRGcm9tIjoiMjAyMC0wMi0yNVQwOTo0ODo1Ny42NjBaIiwiaWQiOiJ2YzpldmFuOnRlc3Rjb3JlOjB4NmU5MGEzZTJiZjM4MjNlNTJlY2ViMGY4MTM3M2ViNThiMWEwYTIzODk2NWYwZDQzODhhYjljZTljZWVkZGZkMyIsImNyZWRlbnRpYWxTdGF0dXMiOnsiaWQiOiJodHRwczovL3Rlc3Rjb3JlLmV2YW4ubmV0d29yay92Yy92YzpldmFuOnRlc3Rjb3JlOjB4NmU5MGEzZTJiZjM4MjNlNTJlY2ViMGY4MTM3M2ViNThiMWEwYTIzODk2NWYwZDQzODhhYjljZTljZWVkZGZkMyIsInR5cGUiOiJldmFuOmV2YW5DcmVkZW50aWFsIn19LCJpc3MiOiJkaWQ6ZXZhbjp0ZXN0Y29yZToweDk2ZGE4NTRkZjM0ZjVkY2QyNTc5M2I3NWUxNzBiM2Q4YzYzYTk1YWQifQ.IC8Zb8a1o3OVRh113DX8OSlZuan8jBo_jOWrD_cxovKZs374KKiSTqZD1Uo-Y4jxxCS3dp845nKKeEtPUO6OQQE" 
  } 
}

Properties of interest:

• id
  • The unique identifier. In case of on-chain VCs this is automatically generated and assigned and can be used to query and revoke the VC. For off-chain VCs any string is a valid value.
• issuer
  • The identity issuing a credential. Is a DID pointing to a DID document.
• credentialSubject
  • id
    • The DID of the subject.
  • data
    • Contains information about the actual credential. Fully customizable.
  • description (optional)
    • If given contains human-readable information about the credential.
• validFrom
  • ISO 8601 timestamp of the time of issuance.
• validTo (optional)
  • If given, the VC automatically becomes invalid at this point of time (ISO 8601 timestamp).
• credentialStatus
  • URL of the evan.network revocation service, allowing status checks about the VC. Only available for on-chain documents (see chapter VC types in evan.network).
• proof
  • Providing information about the provided signature, as well as the signature itself to validate integrity and validity of the VC.

Resolving evan.network VCs

Each VC stored on the evan.network has a unique ID associated to it. VC IDs are of the following format:

vc:evan:[core|testcore]:[VC ID]

// Example:
vc:evan:testcore:0x7df3fb59d86d424095fa8fa7f007757aaf9ee63f0c521c3c0d6e1e40549fa5ba

To resolve a VC ID to its associated document, you can either

• use the Web API, providing an ID at
  https://testcore.evan.network/vc/[YOUR ID]
• or use the blockchain core API

VCs revocation status on evan.network

As discussed in the previous section, although VCs stored on the even.network chain can be resolved, on-chain VCs also consist of a revocation status flag. The revocation flag is used to indicate that an on-chain VC is no longer valid although the initial validTo field provided may still say the VC is valid. The URL to the revocation status of a VC is presented in the credentialStatus.id in the VC. The status end point returns a JSON object with the fields vcStatus and status. Example of queried status of VC is as follows:

{
  "vcStatus": "active",
  "status": "success"
}

Where the vcStatus holds either the value active or revoked.

The status field in this examples does not describe the status of the VC revocation but the status of the request:

• "status": "success" means, that the request against the server was successful and that the VC document could be found.
• “status”: “error” indicates issues with the request. The most common type of issue here could be some issues with the VC document like invalid proof, wrong ID, etc. In those cases have a closer look at the “error”` property in the result to find more about the issue.

VC types in evan.network

Off-chain VCs

Off-chain VCs are locally created VCs. They come with a valid proof. However, they are not stored on the chain and thus cannot be recovered once lost. The evan.network revocation service does not support off-chain VCs. Encryption and sharing mechanisms are supported but have to be implemented manually.

On-chain VCs

On-chain VCs are registered with the evan.network’s central VC registry and stored on the evan.network, being assigned a unique ID. Under this ID the VC can be resolved using the Web API or the blockchain core API.
On-chain VCs can be revoked using the evan.network revocation service and support data encryption and different stages of visibility, which are:

Public

Public on-chain VCs are visible for everybody knowing the ID to query the registry. Therefore an issuer should take care with the data they are attaching to the VC.

Shared

Shared on-chain VCs are encrypted by the issuer. They can be shared with parties (which is done by sharing the respective key material) that then gain access to the issued payload data exclusively.

Private

Private on-chain VCs are a special type of shared VCs where the document is shared with only a single party.

Revocation

Certain credentials might become invalid over time. In this case, the VC for this credential must be revocable to stop the subject from continuing using the now invalid credential.
There are two ways a VC can be invalidated in evan.network:

• A VC was issued for a certain period of time only and has now expired (using the validTo property).
• The issuer revokes the VC using the revocation service and the registry will not allow access to this VC anymore, rendering it invalid.

Checking a VC’s status can be done either using the blockchain-core API or the Web API at
https://testcore.evan.network/vc/status/[VC ID]

Example use case

Imagine a car rental service renting out modern cars that do not require keys anymore. A client wants to rent a car for one day from this company. To be allowed to sign the contract, the client must be 21 years of age or older, and have a driving license. At their 21st birthday, the government issued a VC confirming that this person is now of legal age. Also upon successfully passing the driving test, the DMV issued a VC confirming the client’s obtaining of a driver’s license.
On the other hand, the client needs assurance that the car he is assigned is fit to drive. The company therefore obtains VCs from the country’s technical inspection agency for all their cars, verifying the cars are safe to drive.

On contract negotiation, the rental company verifies the government-issued VCs using the government agencies’ DID documents, obtained from the blockchain (e.g., but not limited to, evan.network), and the key material it is carrying.
Now both of them sign the rental contract with the company, the company issues a VC with the client as the subject, stating that this client is allowed to open and steer a particular car. The client also verifies the VC ensuring the technical integrity of the car. As the contract was closed over a rental duration of one day, the VC is set to expire after 24 hours. This VC is sent to the client.

Standing in front of the car, the client starts interacting with it and sends the issued VC to it. It evaluates that it is the car stated in the VC and verifies the proof of the VC, since it knows its owner’s public key. Only the owner (assuming that no one else has access to the owner’s private key) is able to create a valid proof. If the verification succeeds, the car opens its doors and lets the client take control.