# Credential Lifecycle

This page documents the role and lifecycle of credentials in the IAM stack.

Credentials are documents that allow individuals to show that they possess certain accreditations (this is discussed further in depth [below - 'Credentials Overview'](#credentials-overview)). Credentials are traditionally document or paper-based, such as a driver's license or a passport, and are typically registered in a centralized repository under the stewardship of the issuing body.

*Verifiable credentials* are purely digital components that can be verified cryptographically. Verifiable credentials are a secure and self-sovereign alternative to traditional paper-based credentials or documents, which typically must be physically or electronically transmitted for verification, and have the potential to be intercepted, altered or tampered with.

In general, verifiable credentials do not rely on Decentralized Identifiers (DIDs) but they are often used together. If DIDs are used, decentralized ledger technology (i.e. a blockchain) can provide the public key infrastructure for the cryptographic verification.

The specification that defines verifiable credentials was established and is maintained by the [World Wide Web Consortium (W3C)](https://www.w3.org/). This protocol continues to evolve. Verifiable credentials are one of the three core pillars of [self-sovereign identity](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction), along with [decentralized identifiers (DID)](https://www.w3.org/TR/did-core/) and distributed ledger technology.

{% hint style="info" %}
See the W3Cs use cases and requirements for verifiable credentials [here](https://www.w3.org/TR/vc-data-model/#use-cases-and-requirements)
{% endhint %}

Verifiable credentials are a key component of Energy Web's Identity, authorization and access management. In current use cases, credentials are used to authorize users' or assets' enrolment into applications and organizations. Each credential is associated with the subject's [DID](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction#decentralized-identifiers-dids) that is anchored on the [Energy Web Chain](https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/technology/trust-layer-energy-web-chain/README.md). Energy Web's [Switchboard](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) application provides a user interface for creating, requesting, issuing and revoking role-based credentials. [Energy Web's IAM libraries and APIs](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction#ew-dos-identity-and-access-management-stack) facilitate the full lifecycle of verifiable credentials. The [Energy Web blockchain](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/trust-layer-energy-web-chain) serves as the trust or verification layer for digital proof. This documentation provides references to these libraries, and to supporting [W3C](https://www.w3.org/) documentation that is used to guide and inform the development of Energy Web's IAM solution.

**Click below to see a current diagram of Energy Web IAM architecture:**

{% embed url="<https://s.icepanel.io/gODPIqAQio/l/-/q8qxi31rvqe/fte2ew4ag4i/1192.7/321.4/0.788>" %}
Click to navigate to IAM architecture
{% endembed %}

## Credentials Overview

A [claim](https://www.w3.org/TR/vc-data-model/#dfn-claims) is an assertion that is made about a [subject.](https://www.w3.org/TR/vc-data-model/#dfn-claims) A claim could assert, for example, that a battery meets specific manufacturing standards.

A [credential ](https://www.w3.org/TR/vc-data-model/#dfn-claims)is a claim(s) made by an [issuer](https://www.w3.org/TR/vc-data-model/#dfn-issuers) about a subject. When the credential issuer makes a claim about a subject, they issue a [verifiable credential](https://www.w3.org/TR/vc-data-model/#dfn-claims). For example\_,\_ an issuer can *issue* a credential for a battery that asserts that it was manufactured on a specific date in a specific location.

In order for a credential to *be* verifiable, it must contain a [proof mechanism](https://www.w3.org/TR/vc-data-model/#proofs-signatures) and supporting information to evaluate the proof. The proof must be able to be verified through cryptographic (i.e. algorithmic) means, typically through a digital signature. [Energy Web's IAM libraries support digital signatures of Ethereum-compatible wallets](https://docs.energyweb.org/legacy-documentation/foundational-concepts/wallets-and-exchanges/software-cryptocurrency-wallets/metamask), such as [MetaMask](https://metamask.io/).

**Proofs provide two primary functions:**

1. To verify the authorship of a credential
2. To detect tampering or alteration to the credential/presentation

In the example of the battery mentioned directly above, the proof will verify that

1. The issuer is authorized to assert that the battery was manufactured on a specific date and in a specific location
2. That the credential data and digital signature has not been changed or compromised

Note that proof mechanisms do not validate the facts that the claim asserts (in the example above, the providence of the battery). It only verifies the issuer of the claim and the integrity of the claim's data over time (i.e. has the data been altered or tampered with).

#### Proof Mechanisms

There are two main proof mechanisms for verifying credentials, **both of which are used in the IAM stack*****.*** These will be discussed further below.

1. **External proofs,** which are commonly expressed by [JSON Web Tokens](https://jwt.io/). An external proof is one that wraps an expression of the credential data model, such as a JSON Web Token. See the W3C JSON payload encoding standards for verifiable credentials [here](https://www.w3.org/TR/vc-data-model/#jwt-encoding). Verifiable Credentials expressed as JSON Web Tokens in the IAM stack is discussed[ below](#1-json-web-token-with-eip-191-signature).
2. **Embedded proofs,** in which the proof is included directly in the credential's JSON data. To be compatible with [W3C Verifiable Credentials standard](https://www.w3.org/TR/vc-data-model/#conformance), the credential JSON [must have a property of 'proof'.](https://www.w3.org/TR/vc-data-model/#example-usage-of-the-proof-property-on-a-verifiable-credential) Verifiable credentials expressed as JSON/JSON Linked Data in the IAM stack are discussed [below](#2-json-ld-verifiable-credential-with-eip-712-signature).

## **Credentials in the Energy Web Stack**

The Energy Web IAM stack provides API methods to [request,](#1-request-credential) [issue](#2-issue-credential), [publish](#3-publish-credential), [verify ](#5-verify-credential)and [revoke](#4-revoke-credential) credentials.

Our ecosystem offers persistence for credentials on the [Energy Web blockchain](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/trust-layer-energy-web-chain), and off the blockchain using the decentralized file system [IPFS](https://docs.ipfs.tech/concepts/what-is-ipfs/).

* Credentials that are persisted on the Energy Web Chain are referred to as ['on-chain' credentials](#on-chain-credentials)
* Credentials that are persisted off-chain are referred to as ['off-chain' credentials](#off-chain-credentials)

The distinctions are discussed in the following section.

{% hint style="warning" %}
Note that whether a user chooses to persist credentials on-chain and/or off-chain, credential data is also persisted in the [SSI Hub](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference). SSI Hub facilitates credential exchange by persisting credential request and issuance messages
{% endhint %}

### 'On-Chain' Credentials

On-chain credentials are registered on the [Energy Web blockchain](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/trust-layer-energy-web-chain) in the Claim Manager [smart contract](https://ethereum.org/en/developers/docs/smart-contracts/). The contract source code can be found [here](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimManager.sol). A credential is registered in the contract when the credential is [published](#3.-publish-credential) by the holder.

{% hint style="warning" %}
The [Energy Web Chain](https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/technology/trust-layer-energy-web-chain/README.md) is a public blockchain. **This means that smart contracts and their data are public, and their public methods can be called by anyone.** This is an important point of consideration when deciding whether to publish credentials to the blockchain.
{% endhint %}

<figure><img src="https://2400236058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_pXALj14Egb-5Bal_p%2Fuploads%2Fji1rUS2VAbHlruuvOrMG%2FScreen%20Shot%202022-08-24%20at%2011.58.06%20AM.png?alt=media&#x26;token=35537cdb-e810-4411-a74d-9d08ceed3577" alt=""><figcaption><p>On-Chain Credential Persistence</p></figcaption></figure>

#### Credential Smart Contracts

There are currently two smart contracts deployed on the Energy Web Chain that are used for verifying and persisting verifiable credential data (for 'on-chain credentials' only). The source code for these contracts can be found in the [`@energyweb/onchain-claims` package](https://github.com/energywebfoundation/ew-credentials/tree/develop/packages/onchain-claims/contracts).

| Contract                                                                                                                                                                        |                                            Purpose                                           | Address - Energy Web Chain                                                                                                        | Address - Volta                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Claim Manager** [Source Code](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimManager.sol)                          | Holds mapping of issued verifiable credentials; Provides methods for credential verification | ['0x23b026631A6f265d17CFee8aa6ced1B244f3920C'](https://explorer.energyweb.org/address/0x23b026631A6f265d17CFee8aa6ced1B244f3920C) | ['0x5339adE9332A604A1c957B9bC1C6eee0Bcf7a031'](https://volta-explorer.energyweb.org/address/0x5339adE9332A604A1c957B9bC1C6eee0Bcf7a031) |
| **Claims Revocation Registry** [Source Code](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimsRevocationRegistry.sol) |                 Holds mapping of [revoked credentials](#4.-revoke-credential)                | ['0xd72B4c8D5B1a1A4C7085259548bDF1A175CFc48D'](https://explorer.energyweb.org/address/0xd72B4c8D5B1a1A4C7085259548bDF1A175CFc48D) | ['0x9876d992D124f8E05e3eB35132226a819aaC840A'](https://volta-explorer.energyweb.org/address/0x9876d992D124f8E05e3eB35132226a819aaC840A) |

### 'Off-Chain' Credentials

Off-Chain credentials are not referenced on the blockchain. Off-chain credential data is persisted as a [JSON web token](https://jwt.io/) on [IPFS](https://www.ipfs.com/), a decentralized public filesystem. IPFS, like a blockchain, is a decentralized system and relies on a network of peer nodes to create a distributed system.

When a token is stored on IPFS, it has a [content identifier (CID)](https://docs.ipfs.tech/concepts/content-addressing/) that points to its location on the file system. This CID is linked to the credential's corresponding [DID Document](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction#did-documents) through a [service endpoint](https://www.w3.org/TR/did-core/#dfn-service-endpoints). A service endpoint points to any service that supports or acts on behalf of a DID. The CID is used to fetch and resolve the full credential from IPFS when necessary.

{% hint style="warning" %}
DID Document data, including service endpoints, are publicly available on the Energy Web Chain. **IPFS data is accessible to anyone who has the service endpoint that contains its location on IPFS.** This is an important consideration when deciding to publish credentials to IPFS.
{% endhint %}

<figure><img src="https://2400236058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_pXALj14Egb-5Bal_p%2Fuploads%2FzVT7KsObW7Hj6NptRvCu%2FScreen%20Shot%202022-08-24%20at%204.52.30%20PM.png?alt=media&#x26;token=682e2fa0-f8d4-4846-bff1-82228c6501d4" alt=""><figcaption><p>Off-Chain Credential Persistence</p></figcaption></figure>

#### Off-Chain Credential Schema

For each off-chain credential request, [**`iam-client-library`**](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) **issues two credentials of different format and proof type.**

Both signature mechanisms can be performed by [Ethereum-based wallets such as MetaMask](https://docs.energyweb.org/legacy-documentation/foundational-concepts/wallets-and-exchanges/software-cryptocurrency-wallets/metamask).

#### 1. JSON Web Token with EIP-191 signature

A JSON web token is a common standard for transferring encoded, verifiable data between parties. The [JSON web token](https://jwt.io/) payload is generated from the claim data.

* **Proof Mechanism:** [EIP-191 signature](https://eips.ethereum.org/EIPS/eip-191) standard
* **Data Model**: The JWT payload partially conforms to the properties established by W3C for verifiable credentials as a JWT. You can view these properties [here](https://www.w3.org/TR/vc-data-model/#jwt-encoding).
* **Persistence:** The issued token is included in an object that contains other data about the issued credential request. (Read more about claim issuance [below](#2-issue-credential)). The token is persisted in the SSI Hub's database when the [credential is issued](#2-issue-credential), and persisted in [IPFS](https://ipfs.io/) when a [credential is published](#3-publish-credential) by the subject. The credential's location in IPFS is referenced in the user's DID Document's service endpoints.

#### 2. JSON-LD Verifiable Credential with EIP-712 signature

* **Proof Mechanism:** [EIP-712 signature](https://eips.ethereum.org/EIPS/eip-712) specification. This allows the credential data to be displayed in a human-readable format when digitally signing the message:

<figure><img src="https://2400236058-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_pXALj14Egb-5Bal_p%2Fuploads%2FsbelbASNOyjbUpamzLxm%2FScreen%20Shot%202022-08-24%20at%204.49.06%20PM.png?alt=media&#x26;token=50fc0554-e39e-4557-98ac-d69ac30fdb57" alt=""><figcaption><p>EIP-712 signature request</p></figcaption></figure>

{% hint style="info" %}
See the W3C documentation on the EIP-712 signature [here](https://w3c-ccg.github.io/ethereum-eip712-signature-2021-spec/).
{% endhint %}

* **Data Model/Interface:** The Verifiable Presentation interface conforms to W3C credential schema, which includes [JSON-LD (JSON Linked Data)](https://json-ld.org/) data format. JSON linked data ensure that credentials and presentations are universally machine readable and compatible. Read more about JSON-LD formatting in verifiable presentations and credentials in the W3C documentation [here](https://www.w3.org/TR/vc-data-model/#differences-between-contexts-types-and-credentialschemas).
* **Persistence:** The verifiable presentation is included in an object that contains other data about the issued credential. This object is persisted in [SSI Hub](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) database.

### On-Chain vs. Off-Chain Registration Rationale

In addition to the above, there are a few distinctions to consider when deciding to register credentials off-chain or on-chain.

* On-chain credentials can be read by any smart contract deployed on the Energy Web Chain, and thus used in many decentralized applications. This allows for greater application interoperability.
* Off-chain credentials in IPFS do not require any [transaction costs](https://docs.energyweb.org/legacy-documentation/foundational-concepts/ethereum/transaction-costs) that are associated with a blockchain, and can be resolved by an IPFS client in any application.

## **IAM Stack Credential Lifecycle**

### **1. Request Credential**

A credential request occurs when a user requests to enrol to an organization or application’s pre-defined role. The role may have specified criteria that the subject must meet in order to take on the role. The user who is requesting to take on the role is the claim ‘[subject’](https://www.w3.org/TR/vc-data-model/#credential-subject).

[`iam-client-library`](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) contains high-level methods to initiate credential requests. **These methods indicate whether a credential should be registered** [**'on-chain'**](#on-chain-credentials) **or** [**'off-chain'**](#off-chain-credentials)**.**

Claim requests are persisted in the [SSI Hub](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference).

#### Example

A user makes a request to the credential issuer to enrol into Organization A as a 'Battery Installer'. This role is pre-defined by Organization A, and has a designated set of issuers (each with a [DID](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction#decentralized-identifiers-didshttpswwww3orgtrdid-core)) who are authorized to approve and issue a credential for the 'Battery Installer' role. At the time of request, the subject must specify if they want this credential to be persisted [on-chain](#on-chain-credentials) or [off-chain](#off-chain-credentials).

### **2. Issue Credential**

The credential's issuer approves and issues (or rejects) a subject’s credential request. By issuing the credential, they are verifying that the subjects meets the requirements needed to obtain the credential.

Using the [**example**](#example) \*\*\*\* above, the issuer is issuing a credential of 'Battery Installer' to the subject. In doing so they are asserting that the subject meets the requirements to hold this credential. They are signing the credential (providing [proof](https://www.w3.org/TR/vc-data-model/#proofs-signatures-0)) with their digital signature using an [Ethereum- compatible wallet such as MetaMask](https://docs.energyweb.org/legacy-documentation/foundational-concepts/wallets-and-exchanges/software-cryptocurrency-wallets/metamask).

#### **Issuing** [On-Chain Credentials](#on-chain-credentials)

If a credential has an \*\*'\*\*on-chain' [registration type](https://energy-web-foundation-iam-client-lib.readthedocs-hosted.com/api/enums/modules_claims.RegistrationTypes/), the verified credential is registered in the [Claim Manager smart contract](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimManager.sol).

#### Issuing [Off-Chain Credentials](#off-chain-credentials)

As discussed [above](#off-chain-credential-formats), off-chain credentials are issued in two formats:

1. A [**verifiable presentation**](https://www.w3.org/TR/vc-data-model/#dfn-presentations) \*\*\*\*
2. A signed [**JSON Web token**](#claims-overview)\*\*\*\*

The verifiable presentation and issued token are appended to the claim data, which is updated in the [SSI Hub](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference).

### 3. Publish Credential

Once an issuer has issued a credential, the subject has the option to publish (persist) the credential. The persistence location depend on if the credential is registered [on-chain](#on-chain-credentials) and/or [off-chain](#off-chain-credentials). Persistence for on-chain credentials is discussed above [here](#on-chain-credentials). Persistence for off-chain credentials is discussed above [here](#off-chain-credentials).

### 4. Revoke Credential

The W3C Verifiable Credential protocol includes revocation as a standard operation in the credential lifecycle. Credentials can be revoked due to a breach in proof integrity (digital signature), or because the subject no longer meets the requirements to hold the credential.

The IAM stack provides methods for a [revoker](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/governance#role-definition-properties) to revoke a credential *after* it has been issued.

Revocation for Energy Web credentials is executed based on the [Role Governance](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/governance). Only an authorised revoker (a DID or any DID with specific role credential) can revoke a credential.

#### Revoking [On-Chain Credentials](#on-chain-credentials)

When an on-chain credential is revoked, the revocation is registered in the [ClaimsRevocationRegistry smart contract](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimsRevocationRegistry.sol). This smart contract holds a reference to every revoked credential. The ClaimsRevocationRegistry contract references the [ENSRegistry contracts](https://github.com/energywebfoundation/ew-credentials/tree/develop/packages/credential-governance/contracts) to ensure that the revoker has the right authority to execute revocation and [ClaimManager](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimManager.sol) contract to validate if the subject has the role credential (to be revoked) and if revoker's authoritative credential has either expired or revoked (for the case where revoker's authority is based on a specific role credential).

For a revoker to be able to revoke an on-chain credential, their authoritative credential should also be [published on-chain](#on-chain-credentials).

#### On-Chain Revocation Sequence:

{% @mermaid/diagram content="sequenceDiagram
autonumber
participant R as Revoker
participant CS as ClaimService
participant CR as ClaimsRevocation
participant CRR as ClaimsRevocaitonRegistry
participant CM as ClaimManager
participant ER as ENSRegistry
rect rgb(200, 255, 255)
Note right of R: Revoke on-chain role credential
R->>CS: ClaimService.revokeClaim()
Note right of CS: Revocation client call
CS->>CR: ClaimRevocation.revokeClaim(namespace, subject, revoker)
note right of CS: ew-credentials provides ClaimsRevocation functionality
end
rect rgb(255, 220, 255)
Note right of CS: Revoker authority verificaiton and revocation registration
CR ->> CRR : revokeClaim(namespace, subject, revoker)
CRR->>CM: Validate if subject has given role credential (hasRole(subject, role, version))
CRR->>CRR: Validate if the role is already revoked
Note right of CRR : Revoker authority verification
CRR->> ER: Fetch revokerDefinition for the role
ER-->>CRR: Return revokerDefinition
CRR->>CRR: Validate revoker is in specified revokerDefinition
Note right of CRR: if revoker roleType is role
CRR->>CM: verify revoker has the authoritative role
CRR->>CRR: Register revocation
end" %}

#### Design Rationale

For a credential to be verifiable on-chain, a verifier should be able to check the revocation status of the issued credential along with the issuance.

It should be possible to get a single source of truth for a revocation status i.e. a *verifier* should be able to get a valid revocation from a registry without the need to verify it again.

For a revocation to be registered on-chain it is necessary that the credential first be registered on-chain with [ClaimManager](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimManager.sol), where holder has provided their consent to make the credential publicly available.

The publishing of a holder's credential reduces the privacy and allows someone to determine if a holder has been issued a role credential or not.

In other words, revocation of a credential which has not been published yet would imply that the holder holds the role credential reducing the privacy of the holder's credential.

Therefore, the revocation registry requires that the holder consent to their credential being on-chain and publishing it to the ClaimManager registry.

Having the credential in the ClaimManager allows the [ClaimsRevocationRegistry](https://github.com/energywebfoundation/ew-credentials/blob/develop/packages/onchain-claims/contracts/ClaimsRevocationRegistry.sol) to provide verifiability of:

1. Only verified and valid credential being revoked, ClaimManager verifies credential's integrity and its issuer's authority before registration.
2. Credential's validity with regards to *expiration*.
3. Revoker's authority who revoked Holder's credential.

Thus establishing a design which provides *Verifier* with a trusted mechanism for revocation status check which ensures that *a valid credential can only be revoked by an authoritative revoker*.

#### Revoking [Off-Chain Credentials](#off-chain-credentials)

When an off-chain credential is revoked, the credential JSON is updated with a "*credentialStatus*" property that is conformant to [W3C's StatusList2021](https://w3c-ccg.github.io/vc-status-list-2021/) data model. This data model provides a link for verifiers to use to see the status of a credential (i.e. if a credential has been revoked by the revoker). The verifier can verify this *credentialStatus* property and derive the revocation status of the credential. You can view the properties of the StatusList2021 data model [here](https://w3c-ccg.github.io/vc-status-list-2021/#data-model).

When a credential is revoked using [`iam-client-library`](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference), which utilises [status-list](https://github.com/energywebfoundation/ssi-hub/tree/develop/src/modules/status-list) module to append this *credentialStatus* property to credentials, the *credentialStatus* will have a *statusPurpose* that reflects it has been revoked:

```
credentialStatus: {
    id: 'https://credential-status/admin',
    type: StatusListEntryType.Entry2021,
    statusPurpose: CredentialStatusPurpose.REVOCATION,
    statusListCredential:
      'https://isc.energyweb.org/api/v1/status-list/700xxxxx-5xxx-4xxx-bxxx-43acfaxxxxxx',
    statusListIndex: '0',
  }
```

Status list credentials are persisted in SSI Hub. The *credentialStatus* object has an attribute *statusListCredential* that provides a URL thorugh to fetch the credential's status for verification purposes.

More detailed documentation around *StatusList2021* can be found [here](https://github.com/energywebfoundation/ssi-hub/blob/develop/docs/status-list.md)

### 5. Verify Credential

A verifier is responsible for verifying the authenticity of a credential. The criteria for this evaluation is specified by the W3C Verification standards [here](https://www.w3.org/TR/vc-data-model/#dfn-verify). [`iam-client-library`](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) provides verification methods that evaluates these criteria, namely:

1. The credential proof (typically the digital signature) is valid.
2. The credential is not [revoked](#4-revoke-credential).
3. The credential is not expired.

Beyond the scope of basic verification,[ `iam-client-library's`](https://docs.energyweb.org/legacy-documentation/ew-dos-technology-components-2023/identity-and-access-management-iam/patterns/broken-reference) verification methods also validate the issuer's authorization to issue the credential and does this for all the issuers in the hierarchy.

This verification is executed for off-chain credentials and relies on the subject's (holder or issuer) [DID Document](https://docs.energyweb.org/legacy-documentation/foundational-concepts/self-sovereign-identity-introduction#did-documents) resolution.

#### **Off-Chain Verification Sequence:**

{% @mermaid/diagram content="sequenceDiagram
autonumber
participant H as Holder
participant V as Verifier
participant CS as ClaimService
participant IV as IssuerVerification
participant CR as CredentialResolver
participant PV as ProofVerifier
participant RV as RevocationVerification
participant SH as SSI-HUB
participant IPFS
participant DR as DomainReader
rect rgb(200, 255, 255)
Note right of H: Presentation
H->>V: Holder presents credential to the verifier
Note right of V: Verification Call
V->>CS: ClaimService.resolveCredentialAndVerify
note right of CS: iam-client-lib provides IAM functionalities like ClaimService
end
rect rgb(255, 220, 255)
Note right of CS: Signature and issuer validation
CS ->> CR : Fetches role credential {by DID, namespace}
Note right of CR : CredentialResolver.getCredential(subjectDID,roleNamespace)
CR->> CR: Resolve DID Document from Blockchain
loop For each serviceEndpoint
CR->>IPFS : Resolve credential from IPFS
end
CR->>CR: Match credential witht the provided namespace
CR-->>CS: returns credential
CS->>PV: Verify credential for signature
CS->>IV: issuerVerification.verifyIssuer()
Note right of IV: ew-credentials provides IssuerVerification
loop Verifies issuers in the hierarchy
alt if the verification continues to be true
IV->>RV: verify revocation and expiration status of issuers
IV->>DR: fetch RoleDefinition
DR-->>IV: returns IIssuerDefinition
IV->>IV: validates if current issuer is authorised
IV->>PV: verify issued credential signature
else if verification fails
IV->>CS: returns verification stating the error
end
IV->>IV: verifies next issuer in the hierarchy
end
IV->>CS: returns verification result with verified status true
end" %}

## Related Content

{% content-ref url="<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/technology/trust-layer-energy-web-chain/README.md>" %}
<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/technology/trust-layer-energy-web-chain/README.md>
{% endcontent-ref %}

{% content-ref url="<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/how-tos-and-tutorials/interacting-with-a-smart-contract.md>" %}
<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/how-tos-and-tutorials/interacting-with-a-smart-contract.md>
{% endcontent-ref %}

{% content-ref url="<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/patterns/self-sovereign-identity/README.md>" %}
<https://github.com/energywebfoundation/ewf-gitbook/blob/develop/identity-at-ew/patterns/self-sovereign-identity/README.md>
{% endcontent-ref %}
