Litentry Identity Registrar

Explanation of Litentry (Kusama) identity registrar - a service that leverages cryptographic design to provide judgment on user identity while preserving privacy.

Registrar Background

Decentralized Identity (DID) consists of a triangle of Trust. The attester (registrar), the credential holder, and the verifier. The attester (verifies/attests/judges) that the credentials for the identity are correct. Credentials could be email addresses, Twitter accounts, or any other data that could be used as identity credentials. The credential holder is the person, business, or IoT device that controls the credentials. The verifier is the entity to whom the credentials are being presented.

For example, if you want to use a Dapp or service and they would like to verify that you are identified by your email address and/or Twitter account. They could ask for these credentials. As a user that needs to use this service, you could choose to hand these credentials over to them. Because the credentials are attested by a trusted attester, the verifier will accept the presented credentials and allow you to use the Dapp or service.

Litentry is a registrar in the Polkadot ecosystem (an attester in self-sovereign identity). This means that Litentry can attest to (issue a judgment) the validity of your email address, Twitter account, and any other identifying information. This section covers How to verify your identity with Litentry and the implementation details of Litentry.

Litentry and Polkadot

Polkadot provides a service that allows participants to add personal information such as email addresses and Twitter accounts to their on-chain accounts. The user can then ask for verification of this information by a registrar. Litentry is a registrar. A user can request a registrar to make a judgment on their claims. The user can select a fee that they are willing to pay. Registrars are accepted by submitting proposals to the democratic process in Polkadot and Litentry has been accepted as a Registrar for Kusama.

Implementation Details

GitHub Repository:https://github.com/litentry/litentry-registrar

This document highlights the implementation details of how Litentry works as a Polkadot/Kusama registrar.

Context

When a user has set their identity in Polkadot or Kusama they can request judgment from a registrar. In Polkadot, the registrar can support up to six levels of confidence in their attestation. At the moment Litentry supports four judgment levels and in the future, we would like to support KnownGood by integrating with well-known KYC organizations in the future. The LowQuality level will never be supported by Litentry.

In the implementation details section, the Litentry Registrar Architecture consists of Validators, Event Listener, ProvideJudgement Service, and Database Service. We also introduce a secure method using JWT (JSON Web Token) to construct the verification protocol.

Judgment Levels & Criteria

Registrars on Kusama can provide their judgment according to six levels of confidence for users’ identity:

• Unknown: The default value, no judgment made yet.

• Reasonable: The data appears reasonable, but no in-depth checks (e.g. formal KYC process) were performed.

• KnownGood: The registrar has certified that the information is correct.

• OutOfDate: The information used to be good, but is now outdated.

• LowQuality: The information is low quality or imprecise, but can be fixed with an update.

• Erroneous: The information is erroneous and may indicate malicious intent.

There is another temporary confidence level used by Polkadot/Kusama.

• FeePaid: The judgment has been requested by a user and the information verification is in progress.

In Litentry we add additional clarification for each of these levels.

Reasonable : If a user’s display name, email, and twitter identity are verified. Litentry will update the user's identity as Reasonable

OutOfDate : Litentry registrar keeps track of the user's identity to see whether it’s out of date or not updated regularly enough. If a user doesn’t update his identity timely, his identity will degrade to OutOfDate.

Erroneous: If any attempt is made by the user to attack the Litentry registrar, e.g. DDOS attack, the Litentry registrar will provide judgment with Erroneous and refuse to provide a new judgment for him in a specific period.

LowQuality : The Litentry registrar will never provide a judgment of LowQuality

The Litentry registrar will automatically provide hints to guide the user to update his identity. After all the information is correctly verified, the user will receive a Reasonable judgment. In this way, a user can not only save fees (since we only provide one judgment for him) but also save time (since the Litentry registrar will point out an imprecise or low-quality identity as and when it is captured).

At the current phase, the Litentry registrar does not support providing a KnownGood judgment level since this would require the cooperation of third-party KYC services. We are working on partnering with the appropriate organization so that we can support this level in the future.

Registrar Architecture

Figure 1.1 The Architecture of the Litentry Registrar

The Event Listener listens to all events coming from the Kusama chain. Once a JudgementRequested event is triggered on Kusama and the JudgementRequested indicates to use the Litentry registrar, the Event Listener service will invoke Validators starting the verification process.

At the current stage, the Validators consist of three verification services, Email, Element, and Twitter verification. After receiving the verification request from the Event Listener, the Validator will invoke those verification jobs. They will send a verification link to the users’ provided accounts and wait for user confirmation from their accounts. The email address and Twitter account will be verified by Litentry by sending a challenge message that the user must pass to prove their control of the account. As soon as the user confirms all verification links, the ProvideJudgement service will complete the final step by providing judgment for the user. The implementation details will be introduced in the next section.

Once the user proves the ownership of the Email and Twitter accounts, the ProvideJudgement service will send a JudgementGiven transaction on Kusama to confirm the ownership of the accounts that the user provides.

The Database service will temporarily store users’ data, e.g. Kusama account, email, and Twitter account so that we can recover services from an unpredictable crash. After completing the verification service, those data will be removed from the server permanently.

Figure 1.2 The main Workflow of the Verification process

Security and Availability

We use JSON Web Token (JWT) to construct the verification protocol. A nonce and an ObjectID (from MongoDB) are used to generate the JWT token to ensure the security of the Litentry registrar. In this implementation, only the user who requests identity judgment, which implies his/her ownership of this Kusama account, will receive this encrypted token. Malicious users cannot construct this token because of an unknown encryption secret, since nonce and ObjectID are encrypted. And the malicious user has no way to replay the attacks.

On the other hand, the WebSocket (TCP connection) can be easily reset by the remote peer due to long-time idle. In this situation, the events from Kusama would never be captured due to the disconnection between Kusama and Litentry. To prevent this situation, we capture the events from the underlying WebSocket connection and reconnect to the Kusama automatically whenever the connection is reset by a peer.