Stateless verification with Doughnuts

Doughnuts are digital certificates suited for the blockchain and decentralised era. If you would like to read more about them before getting into how to use them please read this article or this one.

To stay up-to-date on the progress of our technology, follow us on Twitter and LinkedIn, plus join our community on PL^G’s Official Telegram channel.

SingleSource’s KYC protocol has been designed to validate the digital identity of its users. Traditionally, this kind of process is executed via both email and a phone number verification, however, SingleSource is using a stateless solution and the Doughnut protocol to ensure that security, privacy and usability are all maintained throughout the verification process.

Comparing traditional and stateless verification

Traditional email verification is quite simple. A user creates a new profile for an account, which requires verification:

1. The users request is sent to Company A, who stores their email in a database and generates a unique code (this code or token might expire after some time for extra security)
2. Company A then sends the user an email with a link, which includes the generated code
3. Once the user clicks the link Company A can verify the information against the stored email and code
4. The user is then notified of the verification and granted access.

The problem with this model

This process has worked for many years, however, data has become more valuable over this time and led to the increased risk of data leaks, breaches and hacks. Now, data privacy has become an area of liability for current centralised tech systems who store the user’s personally identifiable information. The #OwnYourData movement has seen many users become more conscious of where, how and by whom their personal information is saved, and alternatives to centralisation are high on the agenda.

Stateless Email Verification

To resolve this problem, SingleSource has created a stateless verification that doesn’t rely on storing the user’s data.

1. A user creates a new profile for an account, which requires verification
2. The request to verify their email is sent by Company B to the Email Verification API in the Know Your Customer (KYC) API
3. The user receives an email with a pre-signed ‘Doughnut’, which will appear just like a traditional email verification link
4. The user clicks on the verification link
5. Company B can then check the content and the validity of the Doughnut against the Doughnut Verification API (read more about this under the section Verification Strategies).
6. Once the Doughnut is cryptographically verified, Company B receives the hash data that was inside the Doughnut. If the Doughnut is not verified then the Doughnut Verification API will return the result as ‘false’

Why is a stateless solution better?

Security is built-in. The KYC protocol uses cryptographic verification, rather than centrally storing data, so there isn’t any chance of a data breach. You can think of it like an envelope with a seal. The Doughnut is ‘signed’ when it’s issued and placed in a sealed envelope. The letter and the information inside are then sent to the user, then the client then returned to be validated. We open the letter during the verification process to check the seal is intact and the content is valid.

The seal becomes important during this kind of stateless process. Tampering with the seal would return a false result, but also, if we post it and much later someone shows it to us (with the seal intact) we can still verify the Doughnut (even we don’t have any records of sending that mail).

It’s also easy to integrate the protocol since all actions are REST API based. Finally, it protects the privacy of the end-user and gives them confidence that their data is not being sold without their knowledge.

Stateless phone verification

Verifying a person using their phone is slightly different.

1. The user enters the phone number to be verified in Company B’s web app
2. Company B’s web app sends the request to the Phone Verification API
3. The Phone Verification API generates a Doughnut and sends it to Company B (which contains the hash of the code sent to the user)
4. A six-digit code is also sent to the user
5. Company B displays an input to the user so they enter the CODE they’ve been sent via text message
6. Company B’s web page calls the SDK to verify the Doughnut and check to make sure the CODE is correct
7. The Doughnut is validated and hashed code is given out so Company B can hash the code given by the user and match them. (read more about this under the section Verification Strategies).

Alternatively, the client may also choose to use the Doughnut verification API to verify the Doughnut and the contents inside the KYC domain. This is similar to the email verification flow; the client has the opportunity to use the SDK in this flow since they receive the Doughnut directly from the phone verification API, instead of receiving it via a GET request from the email link, like in the email verification API.

Verification Strategies

Code based for phone verification

This verification must be done in the same session and can use the SDK instead of calling the Doughnut Verification API.

How the Doughnut Verification API works

{API_URL}/doughnuts

This API is designed to verify Doughnuts and return the permissions data in the KYC domain to the user if the user does not ask to verify the data.

First, the Doughnut will be verified to make sure the Doughnut was issued by KYC (comparing the public key of the issuer with that of KYC’s) and checking the EXPIRY, NOT_BEFORE and signature is valid. Next, it will check the contents in the permissions section under the KYC domain:

Request

{

“doughnut”: “{BASE64 ENCODED DOUGHNUT}”

}

Response

Will return to the user only the data in the KYC domain of the doughnut. e.g.

{

{DATA IN THE kyc DOMAIN}

}