Self-Sovereign Identity for Developers

Decentralized identity is starting to create big waves in a world that is increasingly dependent on digital identity and access management. To ride that wave as a developer, do I need to dive into the Verifiable Credential data model or Hyperledger RFCs? Do I need to understand the trust frameworks and the governance around ledgers?

All the above is no doubt useful in understanding the possibilities and limitations of the technology. However, if you just want to get started and write some code, there are easier ways, especially now with tools like Verity, Trinsic APIs, and more recently the Microsoft VC Preview. This article helps you to get started by going through what is involved in using Verifiable Credentials, using Verify as an example. The concepts are similar between all the platforms, but the implementation looks a bit different.

Terminology

Credentials, Schemas and Credential Definitions

Credentials contain information and the necessary metadata to verify that information . Each credential has a list of named attributes, specified by the schema that the credential is based on. The same schema can be used for different purposes by registering a set of credential definitions (or cred def).

Issuers, Verifiers, Holders

Applications that can be used to create new credentials are called issuers. These applications issue credentials to a holder, which is usually a mobile phone application built for storing credentials. A verifier is an application that asks for a holder to share some information from the credentials they hold and verifies the validity of that information.

Agents, agents, agents, and the ledger

All the issuers, verifiers, and holders are agents that communicate with each other using the communication protocols specified for the decentralised identity network. They can also communicate with the public part of the network: the ledger. The ledger holds shared data that must be verifiable by all agents, such as schemas, credential definitions, and issuer identifiers.

How to build an agent?

There are different options to get an agent running. The simplest is to have someone else do it. This is the idea behind the REST APIs that provide an interface to talk to an agent running on the cloud. For Verity, you can request access for Evernym’s Sandbox plan.

When using Verity REST API, you will need to have a public webhook URL for your application that can receive messages from Verity. For a local development environment, tools such as ngrok are very handy. The public URL can be registered for your agent by calling the UpdateConfigs endpoint.

For the end-user, the first step in the process is to connect their agent – usually a wallet application on a mobile phone – with your agent. With Verity, the process looks something like this:

1. Create new relationship (Relationship endpoint, CreateRelationship message)
2. Receive relationship details (RelationshipCreated webhook message)
   • Save the Relationship DID for later use
3. Create invitation to connect (Relationship endpoint, RelationshipInvitationRequest message)
4. Receive invitation details (RelationshipInvite webhook message)
5. Encode invite URL into a QR code
6. <User scans the QR code and accepts the connection in the Evernym Connect.Me wallet>
7. Receive confirmation (ConnResponseSent webhook message)

Now you have the relationship DID which can be used to communicate with the user’s wallet application.

How to build an issuer?

To build an issuer application, you first need to register the issuer. With Verity, you can do that by calling the REST endpoint IssuerSetup. Registration will give you a DID and verKey (public key). Before using the issuer, you also need to register the DID and verKey on the ledger, which in the case of Verity is the Sovrin network. For testing purposes, you can do this yourself (or automatically) at https://selfserve.sovrin.org.

Next, you can either use an existing schema if you know one that fits your purpose or register a new one. Schema registration with Verity can be done by calling WriteSchema with the schema name, version number, and the list of attribute names. You will get back the schema ID that you will need later.

Registering the credential definition is a very similar process. This time you will need to use the WriteCredDef endpoint and provide the schema ID, credential definition name, a tag (for differentiating between multiple cred defs that have the same name and same issuer), and details about revocation.

The issuing itself can be done by following these steps and referencing the relationship DID retrieved in the previous stage:

1. Send credential offer (IssueCredential endpoint, SendOffer message)
2. <User accepts the credential>
3. Receive confirmation notification (SentIssueCredMsg webhook message)

The credential offer contains a value for each attribute defined in the schema. When the user accepts the offer, a new credential will be added to their wallet.

How to build a verifier?

Building a verifier is considerably simpler than building an issuer. There is nothing that needs to be registered on the ledger. The verifier only needs to read the publicly available information from it.

A proof request includes a list of attribute names and the associated restrictions that the verifier wishes to receive. When the user sends the proof response, each attribute needs to follow the restrictions set for it, or otherwise the proof is not valid. The most common restriction is that the attribute must come from a credential with a specific schema ID. Restrictions can also specify the schema issuer DID, schema name or version, the credential issuer DID, or the credential definition ID.

A verifier can request a proof from a holder with the following steps, using the relationship DID of a connection to identify the holder:

1. Send a proof request (PresentProof endpoint)
2. <User receives the request and sends the proof>
3. Receive proof result (ProofResult webhook message)
   • Check that the proof is valid and read the details from RequestedProof

Now the verifier can read the value of each of the requested attributes.

Wrap-up

This was a high-level introduction to self-sovereign identity from the developer perspective, but it has all the necessary building blocks for you to start experimenting with the technology.

I hope you found the post interesting! If you are as excited about SSI as I am, make sure to sign up to our SSI webinars, and follow our blog for more content.