In this paper, our goal is to address an issue related to the exchange process of verifiable credentials, and suggest a first standard solution to be used by the Self Sovereign Identity community.
Verifiable Credentials and Verifiable Presentations are described as standard objects in the W3C web pages (https://www.w3.org/TR/vc-data-model/ ). If implemented as defined there, different providers can be interoperable with each other because the data structure during the exchange can be verified against the standard definition.
However, one of the issues we have discovered through our work at sideos is how to exchange the data among the actors in a digital interaction. We have tested several issuers of Verifiable Credentials and each of them used a different mechanism to provide such information to the holder. In many cases, the answer to how they exchange such information is not documented. As a consequence, these Verifiable Credentials are either very difficult to use, or can only be used with their provided app.
We will try to use the standard definitions of the W3C Verifiable Credentials and Verifiable Presentations to achieve and document a standard process to exchange data during an interaction. This will make the exchange of Verifiable Credentials interoperable if the process described in the following paragraphs is used.
Definitions
As described in the W3C pages, a Verifiable Credential is essentially a JSON object, which contains a structured data model and can be delivered for use. If multiple Verifiable Credentials need to be delivered, a Verifiable Presentation can be used to include multiple Verifiable Credentials in the same envelope, thus delivering a whole set of them together.
The context for which we are describing the following processes is a web interface. We therefore assume that the exchange is done via a web browser and a mobile device. For this discussion, we also assume the use of a JWT to package the Verifiable Presentations and Verifiable Credentials, which can then, for example, be digested by the device via a QRCode. Other ways of packaging the information will work as long as it is standard and well defined.
We will use a Verifiable Presentation envelope to propose a standard method to exchange Verifiable Credentials as well as the specific fields “domain” and “challenge”. These fields are part of the “proof” object defined in the standard definition of the model for the Verifiable Presentation. By combining the “domain” and “challenge” fields together, a complete URL can be created. A callback endpoint can be built at that address to receive information from the consumer of the Verifiable Presentation.
The Flows
During an interaction there are essentially two data exchange flows: Either a Verifiable Credential is offered to a holder by an issuer, or is requested by a verifier from a holder.
Let’s call them “Credential Offer” and “Credential Request”, therefore we can create two new types in the Verifiable Presentation “type” field and we can name them “CredentialOffer” and “CredentialRequest”.
Credential Request Flow
In this flow the verifier packages a Verifiable Presentation and sets the “domain” and “challenge” fields to its backend endpoint callback to verify the data sent by the holder. The application on the holder’s device digests the JWT sent by the verifier, and by using the standard model described in the W3C definitions, parses the JWT and verifies it.
Once the JWT is verified, the application can now check what type of interaction needs to be performed, i.e. whether it is a request or an offer. By checking in the “type” field of the Verifiable Presentation the application can identify the request type, in this case we assume it is a “CredentialRequest”.
At this point, the application on the holder’s device knows that it has to answer the verifier with the Verifiable Credentials requested in the “verifiableCredential” object within the Verifiable Presentation.
Once the application has packaged the answer in a Verifiable Presentation, it is ready to send it back to the verifier using a POST method in the API endpoint identified by the “domain” and “challenge” fields. The application can then post the packaged JWT with the answer to the endpoint.
Credential Offer Flow
In this flow, the issuer packages a Verifiable Presentation and sets the “domain” and “challenge” fields to its backend endpoint callback to confirm the data, which will be sent back by the holder. The application on the holder’s device digests the JWT sent by the issuer, and by using the standard model described in the W3C definitions, parses the JWT and verifies it.
Once the JWT is verified, the application can now check what type of interaction needs to be performed, i.e. whether it is a request, or an offer. By checking in the “type” field of the Verifiable Presentation, the application can identify the request type. In this case we assume it is a a “CredentialOffer”.
At this point, the application on the holder’s device knows that it has to answer the issuer with the acceptance of the Verifiable Credentials received in the “verifiableCredential” object within the Verifiable Presentation.
Once the application has packaged the answer in a Verifiable Presentation, it is ready to send it back to the issuer who is now able to receive the signed Verifiable Credentials. In order to do that, the application uses a POST method in the API endpoint identified by the “domain” and “challenge” fields. The application can then post the packaged JWT with the answer to the endpoint.
Verifiable Presentation Adoption
In order to exchange data between entities all parties need to agree on where to send and receive the VCs necessary for the services to work correctly. In most cases, QRCode encoded JWT (Json Web Token) VCs and VPs are the first step to being able to correctly ingest data from a service to a device.
If two entities know each other, ingesting a VC via a QRCode is very straightforward as the recipient just parses the content, verifies it, and eventually stores it in his storage area. But what happens when two entities do not know each other? How are they going to exchange information just by reading a QRCode?
Some solutions provide a web address on the QRCode data where the recipient should go to retrieve the next piece of information. However, these web services provide a URL where the recipient executes a GET request. This makes it difficult to send any other information attached, as that would require to know what exactly the service can or cannot accept. Therefore, multiple steps are required and this solution is not scalable as there isn't any convergence on how to create these web-based URL endpoints yet.
If we use the model of the VP described in the W3C standards, we could achieve a more concise and defined way to exchange information, which will in turn lead to a more interoperable model.
In the example above, a better data exchange model with the same results could have been achieved by adding a VP containing the request or offer to the QRCode. The recipient will need to parse the content of the VP, and based on whether the VP contains an “offer” or a “request” will either provide or accept the exchanged data.
In the examples that follow below the three flows are explained using the standard W3C VP envelope and the standard W3C VC model.
Summary
As you can see, the flows are essentially the same and they are interoperable as long as the provider uses the described process to create the JWT packages to be exchanged. We, at sideos, currently use this method which has given us the ability to really ease the infrastructure and the integration effort for our customers. We believe the process described in this paper to be a first proposal to standardize the exchange flows and further facilitate the expansion of Self Sovereign Identity services. Comments, improvements, and constructive criticism are always welcome.
Sending a request for a VC
In this example, the issuer would like to request a specific VC via a secure established channel. The issuer creates a VP including the request of the VC he would like to receive. Once the recipient receives the request, he can either accept it or deny it. If accepted, the recipient will send the fully signed VC stored in his wallet.
We assume the secure channel has been established and it has the level of assurance required by the parties involved.
In the following example, the fields in bold clarify the parts involved in the parsing process.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation", “CredentialRequest],
"verifiableCredential": [{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/1872",
"type": ["VerifiableCredential", "EmailVerified"],
}],
"proof": {
"type": "RsaSignature2018",
"created": "2018-09-14T21:19:10Z",
"proofPurpose": "authentication",
"verificationMethod": "did:sideos:v001:ead90029adbb23421290921de#keys-1",
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "https://cloud.sideos.io/consumerequest",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
4vGHSrQyHUGlcTwLtjPAnKb78"
}
}
Sending a request to accept a VC
In this use case the issuer would like to offer a specific VC via a secure established channel. However, the issuer does not yet know the DID of the destination, as there are no prior interactions. Consequently, the issuer has to trust this channel as that is the only source of security available.
The issuer creates a VP, which includes the offer of the VC the offer of the VC and sends it to an anonymous recipient of his choice. Once the recipient receives the offer, he may accept or deny it. If accepted,the issuer will then send back the fully signed VC. Contrary to the first example, the DID of the recipient is now known and it will be part of the VC issued since the DID was provided in the response during the previous exchange.
We assume that the secure channel has been established, and has the level of assurance required by the parties involved.
In the following example, the fields in bold clarify the parts involved in the parsing process.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation", “CredentialOffer],
"verifiableCredential": [{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/1872",
"type": ["VerifiableCredential", "EmailVerified"],
"issuer": "did:sideos:v001:ead90029adbb23421290921de",
"issuanceDate": "2021-08-23T19:73:24Z",
"expirationDate": "2021-08-23T22:73:24Z",
"credentialSubject": {
"id": "did:unknown",
"email": “user@sideos.io
},
}],
"proof": {
"type": "RsaSignature2018",
"created": "2018-09-14T21:19:10Z",
"proofPurpose": "authentication",
"verificationMethod": "did:sideos:v001:ead90029adbb23421290921de#keys-1",
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "https://cloud.sideos.io/consumeoffer",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
4vGHSrQyHUGlcTwLtjPAnKb78"
}
}
We will encode this VP as a JWT, and send it to the recipient via the secure channel. Once the recipient receives the VP, the flow described below will apply.
The recipient parses the JWT and verifies it using the public key of the issuer. The public key is obtained by resolving the DID.
Once verified, the recipient parses the “type” of VerifiablePresentation and sees that it is a “CredentialOfferRequest”. He now has the possibility to either accept or deny such an offer.
The recipient inspects the VC object and displays the content.
If accepted, the URL needed to send the acceptance is built by looking at the “domain” and “challenge” fields and then composing a VP with an offer acceptance, which will be signed and completed by the acceptance DID. Posting the VP to the URL + challenge will make sure the issuer can now respond with the complete VC, which will then be stored.
The flow is completed and the parties have exchanged data.
As you can see, this solution can be implemented by anyone just by looking at the standard W3C formats of VP and VC. Interoperability is achieved by following the process as described.
If the issuer already knows the recipient, the whole "presentation" exchange can be avoided by just sending the final VC through the channel.
We will encode this VP as a JWT, and send it over the channel to the recipient. Once the recipient receives it, the following flow will apply.
The recipient parses the JWT and verifies it using the public key of the issuer.The public key is obtained by resolving the DID.
Once verified, the recipient parses the “type” of VerifiablePresentation and sees that it is a “CredentialRequest”. He now has the possibility to either send a stored VC or deny such a request.
The recipient inspects the VC object and displays the content to the final user.
The user then selects the appropriate fields to send.
If accepted, the URL needed to send the VC is built by looking at the “domain” and “challenge” fields and then composing a VP with the VC requested.
Posting the VP to the URL + challenge will make sure the issuer has received what he expects and proceeds with his flow.
The flow is completed and the parties have exchanged data.
As you can see, this solution can be implemented by anyone just by looking at the standard W3C formats of VP and VC. Interoperability is achieved by following the process as described.
Sending a request together with a possible offer for a VC
In this example, the issuer would like to request a specific VC via a secure established channel. The issuer creates a VP including the request of the VC he would like to receive. Once the recipient receives the request, he can either accept or deny it. If accepted, the recipient will send the fully signed VC stored in his wallet.
If the recipient does not have the requested credential, he/she may accept the one that is being offered. In fact, this type of presentation contains an offer as well as a request. If the recipient accepts the offer, the process follows as in the paragraph “Sending a request to accept a VC”.
We assume that the secure channel has been established and it has the level of assurance required by the parties involved.
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation", “CredentialOfferRequest],
"verifiableCredential": [{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"id": "http://example.edu/credentials/1872",
"type": ["VerifiableCredential", "EmailVerified"],
"issuer": "did:sideos:v001:ead90029adbb23421290921de",
"issuanceDate": "2021-08-23T19:73:24Z",
"expirationDate": "2021-08-23T22:73:24Z",
"credentialSubject": {
"id": "did:unknown",
"email": “user@sideos.io
},
}],
"proof": {
"type": "RsaSignature2018",
"created": "2018-09-14T21:19:10Z",
"proofPurpose": "authentication",
"verificationMethod": "did:sideos:v001:ead90029adbb23421290921de#keys-1",
"challenge": "1f44d55f-f161-4938-a659-f8026467f126",
"domain": "https://cloud.sideos.io/consumeoffer",
"jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..kTCYt5
XsITJX1CxPCT8yAV-TVIw5WEuts01mq-pQy7UJiN5mgREEMGlv50aqzpqh4Qq_PbChOMqs
LfRoPsnsgxD-WUcX16dUOqV0G_zS245-kronKb78cPktb3rk-BuQy72IFLN25DYuNzVBAh
4vGHSrQyHUGlcTwLtjPAnKb78"
}
}