Verifications

Verifications are the mechanism through which data is requested from Verifiable Credentials, usually held in a digital wallet.

At a high level, verifications follow a specific pattern:

The verifier must first understand their risk policy. What will they accept? How will they know whether to trust the verification? These policies are known as "Verification Policies".
The verifier requests some information from the credential holder. This request is known within Trinsic as a "verification request" and is called a "proof request" or "presentation request" in other circles.
The holder will then choose whether/how to satisfy the request and send a response back to the verifier. The response is known within Trinsic for simplicity's sake as a "verification" but is also more accurately called a "proof presentation" or simply a "proof".
Once the verifier receives the verification from the holder, they will check the digital signatures, content, and revocation status against the ledger to ensure validity.
If it all checks out, the verifier will see isValid = true and the verification passes!

How verifications work

Verifier

A Verifier will only verify credentials in the context of some workflow or policy. For example, a bouncer at a bar might accept your driver's license as a proof-of-age but not a student ID. A long-term care facility might require a negative COVID-19 test in the last 72 hours from a reputable lab to admit visitors into the facility. Therefore, part of getting set up as a verifier is understanding your policies for risk and assurance. Once you do, you'll want to set up a Verification Template.

Verification Templates

Verification templates are just that; reusable templates for verifications. They are composed of one or more policies. They are stored with the verifier (not a ledger or other public source). They can be easily deleted and created. They're best for verifications where

You are doing the same verification frequently
You need to check for revocation as of a certain time in the past (but not in real-time, see "Revoking Credentials" guide for more information on revocation)
Your policies are known in advance

The Trinsic Studio allows you to create verification templates. The Credential API allows you to build more flexible workflows without templates.

Verification Policies

Policies declare which data attributes a verifier will request from a holder, and any conditions that those data must meet. There are two types of policies a verifier can create.

1. Attribute Policies

Attribute policies allow you to request data simply based on the attribute name, such as "Name" or "Age." Attributes must be entered exactly as they are used in the corresponding schema. If I request an "AGE" attribute, and all you have are credentials with "Age" attributes, the verification won't be able to be completed.

2. Predicate Policies

Predicate policies leverage zero-knowledge proofs to verify that data meets a certain condition. For example, if a liquor store wanted to know if you were of age, it would create a predicate policy to check whether "Age" is greater than the legal threshold. The liquor store will only receive a "true" or "false" value.

Predicate proofs have four possible types: >=, >, <=, and <. The value name must match the attribute name exactly, both in spelling and in capitalization in order to be recognized. Because the operations are arithmetic, only numbers can be used with predicate policies.

Credential Restrictions

Credential restrictions allow the verifier to ensure they can trust the verification they get back. For example, a liquor store may choose to restrict their verifications to only allow government-issued documents. To do that, it would restrict by issuerDid but they could also restrict in other ways, see below.

schemaId: Anyone who creates a credential with a certain schema ID can issue it to an individual. The schema ID only provides trust that the data is in the correct format.
credentialDefinitionId: Because a Credential Definition is signed by an issuer, the Credential Definition defines both the format of the data and also who sent it to the wallet. This is the most commonly used restriction when constructing definitions. The Credential Definition would be an ID that is written to the Sovrin Ledger, and will prove that the credential an agent sends to you is both issued by the organization and is in the format that you need.
issuerDid: For situations where you only care about where the credential is from and not what format the data is in, you may also use only the issuer's DID. This is also resolvable on the Sovrin Network and will prove that the data you have received was sent from a trusted source. It will not provide any information around the format of the data that you're receiving.

As the ecosystem grows, the ability to discover trusted issuer DIDs, schema IDs, or credential IDs will get easier. For now, a useful tool is indyscan.io, which allows you to browse the Sovrin Networks for these artifacts.

Verification Requests

The first step of a verification process is for a request to be sent by the verifier to a credential holder. The request is generated from a verification template. The request step is very important because it contains a cryptographic challenge that the holder must respond to. In so doing, the verifier can be sure that the holder is responding to this specific verification request and isn't a fraudster performing a Replay Attack.

The Holder's Response

The credential holder can decide what to do with the request they get. They can either

Reject the request, or
Choose from their wallet which credentials they'd like to use to satisfy the request

When the holder responds to the verifier's request, they generate a nonce that satisfies the cryptographic challenge the verifier originally sent.

Doing the Verification

When the verification record is returned to the verifier, it needs to be verified against the ledger to ensure validity (I know, terminology is a bit of a challenge here). Inside the verification record are some metadata, not just the attributes themselves. This metadata includes the digital signatures of the issuer(s) of the credential(s) used, revocation details, verification policy details, etc. which are checked against the relevant sources. If the verification passes, the API will return an isValid field of true (and conversely, a false for failures).

Connectionless Verifications

One useful tool inside of the verifications suite is the ability to create connectionless verifications (see Connectionless Exchanges for more information). Essentially, you can create a verification request without the connectionId parameter. The API will return a verificationUrl that can be shared in a link or encoded as a QR Code.

These types of verifications are most useful when you don't need to have an enduring relationship with the credential holder, or when you might need several people to conduct the same verification. Examples might include one-time train tickets or COVID-19 test results.

Verification Proposals

What happens if the holder does not want to wait for a verifier to initiate a verification flow? Verification proposals implement Aries RFC 0037: Present Proof Protocol 1.0. In the proof protocol, there is an optional first step known as "Propose Proof". A verification proposal flow would follow these steps:

Wallet holder communicates to the verifier that it would like to present a credential.
The verifier responds with a verification request for said credential.
The wallet holder responds with the credential completing the verification flow.

To use verification proposals see Send verification from policy.

Reference App

Check out our verifier-reference-app on GitHub for an example of how to simulate a request of proof of a passport.

How to use in Trinsic APIs

In the Credentials API, you can perform the following functions with Verifications: