1 of 100

SSI Kit

General

Introduction

Discontinuation Notice

Important: Please be informed that, beginning from December 2023, the SSI Kit will no longer receive new features. Furthermore, the SSI Kit is planned for discontinuation by the end of Q3 2024. However, all functionalities offered by the SSI Kit will be integrated into our new libraries, APIs, and apps in the walt.id identity repo. Giving you more modularity, flexibility and ease-of-use to build end-to-end digital identity and wallet solutions. Read the transition guide here. For any clarification or queries, feel free to contact us as we aim to make this transition as smooth as possible.

This documentation will help you understand how the SSI Kit works and how you can use it. However, it presumes a certain level of knowledge about Self-Sovereign Identity (SSI) so

if you are already familiar with SSI, you can jump to the introduction of the SSI Kit.
if you are new to SSI, please continue with our introduction to Self-Sovereign Identity.

Transition To The Community Stack

The Community Stack

It has always been our goal to provide developers and organizations with great tools, so they can focus on delivering holistic identity solutions. Taking the lessons learned from previous products, we decided to redesign our current offering, resulting in what we now call The Community Stack. A collection of open-source products providing everything to launch any identity solution with ease. You can learn more about it here.

Transition

Starting from December 2023, the SSI-Kit will halt feature enhancements, leading to a complete discontinuation planned for end-Q3 2024. It's essential to plan your transition to the new stack effectively. The table below indicates which components of the SSI-Kit are already supported in the new stack.

For Kotlin/Java projects where SSI-Kit was used as a native dependency, utilize the provided Library for equivalent features in the new stack. •
If you employed the REST APIs, simply switch to the supplied API in the new stack.

If you have any question, please reach out.

All relevant new libaries and APIs have found it's place in the waltid-identity repo.

SSI-Kit Feature

The Community Stack

SSI Kit | Basics

Learn what the SSI Kit is.

The SSI Kit offers everything you need to use Self-Sovereign Identity (SSI) with ease.

The following sections elaborate the SSI Kit's unique properties, enabled functionality and components.

Overview

Here are the most important things you need to know about the SSI Kit:

It is written in Kotlin/Java. It can be directly integrated (Maven/Gradle dependency) or run as RESTful web-service. A CLI tool allows you to run all functions manually.
It is open source (Apache 2). You can use the code for free and without strings attached.
It is a holistic solution that allows you to build use cases “end-to-end”. There is no need to research, combine or tweak different libraries to build pilots or production systems.
It abstracts complexity and low-level functionality via different interfaces (CLI, APIs). Additional services facilitate development and integration (e.g. Issuer and Verifier Portals).
It is modular, composable and built on open standards allowing you to customize and extend functionality with your own or third party implementations and to preventing lock-in.
It is flexible in a sense that you can deploy and run it on-premise, in your (multi) cloud environment or as a library in your application.
It enables you to use different identity ecosystems like Europe’s emerging identity ecosystem (EBSI, ESSIF) in anticipation of a multi-ecosystem future.

Functionality

The SSI Kit establishes an identity infrastructure layer for any use case in any industry. Its core services are in the scope of:

Registry Interactions (e.g. read, write; agnostic towards the underlying tech e.g. DLT, DNS)
Key Management (e.g. generate, sign, import, export, manage lifecycle)
Decentralized Identifier (DID) operations (e.g. register, resolve, manage lifecycle)
Verifiable Credential/Presentations (VC, VP) operations (e.g. create, issue, present, verify)
Ecosystem specific use cases (e.g. onboarding, data exchange and monetization)

Illustration:

Components

Signatory | For Issuers

Signatory allows you to digitize paper credentials and automate data provision to your stakeholders.

It provides all functionality required by “Issuers”. For example:

Process and authenticate data requests by people or organisations,
Import data (from local storage or third parties),
Create re-usable VC templates,
Create VCs in different formats (e.g. JSON/JWT, JSON-LD),
Sign VCs using different key types (e.g. ed25519, secp256K1, RSA),
Manage the lifecycle of VCs (e.g. revocation).
Issue VCs (e.g. via OIDC/SIOP)

Custodian | For Holders

Custodian is a secure data hub for people and organizations. It provides all functionality required by “Holders”. For example:

Interact with Registries (read, write)
Create, store, manage keys, data (DIDs, VCs) and other secrets,
Request and import data (VCs) from third parties,
Selectively disclose data (VCs/VPs) for authentication and identification,
Manage consent and data access in a user-centric fashion.

Auditor | For Verifiers

Auditor allows you to verify your stakeholders’ identity data and offer frictionless access to services or products. It provides all functionality required by “Verifiers”. For example:

request data (VCs/VPs) from stakeholders,
verify data (VCs/VPs; incl. integrity, validity, provenance, authenticity),
trigger pre-defined actions following the verification.

Verification Policies

The verification steps can be dynamically configured by passing "verification policies" to each verification attempt.

The SSI Kit comes with the following set of built-in verification polices:

SignaturePolicy: Loads or resolves DID, loads public key and verifies the credentials signature.
JsonSchemaPolicy: Validates the credential against the JSON schema.
TrustedSchemaRegistryPolicy: Checks if the JSON schema is anchored in the EBSI Trusted Schema Registry.
TrustedIssuerDidPolicy: Checks if the issuer DID is anchored on the EBSI DID registry.
TrustedIssuerRegistryPolicy: Checks if the issuer got inserted in the EBSI TIR (Trusted Issuer Registry).
TrustedSubjectDidPolicy: Checks if the issuer DID is anchored on the EBSI DID registry.
IssuedDateBeforePolicy: Checks if issued date is in the past.
ValidFromBeforePolicy: Checks if valid-from date is in the past.
ExpirationDateAfterPolicy: Checks if expiration-date is in the futrue.
CredentialStatusPolicy: Checks if credential is revoked based on the credential-status list.

SSI Kit

This section elaborates the theory behind the SSI Kit:

SSI Kit | Basics - Learn what the SSI Kit is and what it does.
SSI Flavors & Ecosystems - Learn which SSI flavors and identity ecosystems we support.
Architecture - Explore the SSI Kit's multi-layered architecture and components.
Use Cases - Explore use cases you can implement with the SSI Kit.
SSI-Kit feature list - Explore all features in an overview list.

SSI Flavors & Ecosystems

The SSI Kit abstracts complexity for developers by following a "multi-stack approach" that enables you to use different implementations or "flavours" of SSI.

As a result, you can participate in different identity ecosystems (e.g. EBSI/ESSIF, Gaia-X, Velocity Network, cheqd and IOTA) and avoid technology-related lock-in effects.

Based on our Introduction to Self-Sovereign Identity (SSI), we distinguish the following concepts or building blocks:

Read on to learn which concrete technologies and implementations we support on the level of

Trust Registries
Keys
Decentralized Identifiers (DIDs)
Verifiable Credentials (VCs)
Data Exchange Protocols

Trust Registries

Our products are agnostic towards the underlying technologies used to implement Trust Registries, which means that the SSI Kit is potentially compatible with any type of Trust Registry.

The SSI Kit supports:

Permissionless Blockchains (e.g. Ethereum),
Permissioned Blockchains (e.g. Ethereum Enterprise/Hyperledger Besu),
Domain Name Service (DNS),
Pure peer-to-peer approaches that do not require Registries.

Note that we are continuously adding support for new Registries and underlying technologies.

You can learn more about Trust Registries here.

Keys

Cryptographic keys convey control over digital identities and enable core functionality such as encryption and authentication.

The SSI Kit supports:

EdDSA / ed25519
ECDSA / secp256k1
ECDSA / secp256r1
RSA

Note that we are continuously adding support for new key types.

You can learn more about keys here.

Decentralized Identifiers (DIDs)

Our open source solutions enable you to use different types of DIDs and different identity ecosystems. Every relevant functionality is supported from the generation of DIDs and DID Documents to anchoring or resolving them on/from Registries.

We currently support the following DID methods:

did:ebsi
did:web
did:key
did:jwk
did:iota
did:cheqd

Note that we are continuously adding support for new DID methods.

You can learn more about DIDs here.

Verifiable Credentials (VCs)

Verifiable Credentials (VCs) are digital identity documents that can easily and securely be shared with and verified (incl. validity, integrity, authenticity, provenance) by anyone in a privacy preserving way. Importantly, they are never (!) stored on a blockchain due to privacy and compliance reasons.

The SSI Kit supports W3C Verifiable Credentials in different formats:

JSON / JWT
JSON-LD

Note that we are continuously adding support for new VC types and formats.

You can learn more about VCs here.

Data Exchange Protocols

Authentication and data exchange protocols (e.g. OIDC/SIOP) enable the exchange of data (VCs) between different parties.

The SSI Kit supports latest OpenID Connect extension for SSI:

The implementation of the protocols is conformant with the latest specs from EBSI https://api-conformance.ebsi.eu/docs/wallet-conformance

You can learn more about protocols here.

Architecture

The architecture of the SSI Kit consists of three layers:

Low-Level Services Abstraction: Abstracts complex, low-level operations (e.g. cryptography, key management, digital signatures, data storage).
Ecosystem Abstraction: Abstracts ecosystem-specific requirements based on the relevant technical and governance frameworks (e.g. SSI flavors, business logic, policies).
High-Level Interfaces / APIs: Provides high-level interfaces that hide complexity and facilitate usage for developers.

Also, the architecture allows for the integration of third party solutions throughout the stack. For example:

Key storage (e.g. HSM, WebKMS)
Data storage (e.g. identity hubs, confidential storage)
Registries (e.g. blockchains, DNS)

This architectural openness prevents vendor lock-in and allows you to build SSI-based solutions that meet your unique requirements.

Illustration:

Read on to explore all three abstraction layers in more detail.

Low-Level Service Abstraction

This software-layer holds a set of generic core services for common SSI and cryptographic functions. The services are in the scope of key management, decentralized identifiers, verifiable credentials and data storage.

The low-level services expose comon interfaces that can conviniently unitized directly via Kotlin/Java or via the REST API (Swagger doc of the core API).

The following is a short summary of the interfaces available. The detailed functions are described in the documentation further on.

Key Interfaces

Handles keys and cryptographic operations like the generation of signatures (e.g. linked data, JWT) with signature types such as ES256K or EdDSA.

Keys can be stored in a file and database keystore, which is extendable to HSMs and WebKMS.

DID Interfaces

Abstracts common functionality related to Decentralised Identifiers (DIDs, DID Documents) for methods like “did:web”, “did:key”, “did:ebsi”.

Credential Interfaces

Abstracts common functionality related to Verifiable Credentials (VCs) and Verifiable Presentations (VPs) in different formats like JSON and JSON-LD.

Ecosystem Abstraction

We believe in a multi-ecosystem future.

This is why we built an abstraction layer for ecosystem-specific operations and business logic. The idea is to support any ecosystem with a single solution that does not put any additional burden on developers. As a result, you can use our solutions to participate in different ecosystems without having to switch between different technical implementations.

We currently support:

EBSI/ESSIF (EU's new decentralized identity ecosystem)
Gaia-X (EU's new cloud infrastructure)
Velocity Network
cheqd Network
IOTA

Note that we are continuously adding new ecosystems.

High-Level Interfaces / APIs

The SSI Kit exposes high-level interfaces / APIs to hide the complex introduced by

low-level services (e.g. key management, signing, data storage)
different ecosystems (i.e. different SSI flavors, business logic and governance frameworks).

The functionality of the high-level interfaces correlate with the SSI Kit Components. The functions are grouped around:

issuing Verifiable Credentials by the Signatory,
holding (storing, presenting) Verifiable Credentials by the Custodian
and verifying Verifiable Credentials by the Auditor.

The interfaces can be used in JVM-based applications directly, or via the REST API.

The Swagger documentation can be found under section REST API.

Use Cases

Use cases you can build with the SSI Kit.

You can use Self-Sovereign Identity (SSI) - and by extension the SSI Kit - to solve any identity-related problem.

Identity and Access Management (IAM, CIAM)

You can use the SSI Kit to enable your users, customers, employees or partners to access information, services or products. By this, you can replace today's cumbersome sign-up and login processes (usernames, passwords) with more seamless experiences.

In other words, you can SSI to authenticate stakeholders you already know.

Identity Proofing / Verification

You can use the SSI Kit to identify people, organizations or even things to provide them with information, services or products.

Identity proofing is particularly important in the AML (anti-money launder) regulated industries, but is seeing growing adoption by non-regulated industries and platforms to prevent fraud, SPAM and other malicious behaviour.

Simply put, you can use SSI to identify stakeholders you do not yet know.

Risk and Compliance Checks

You can use the SSI Kit to verify any identity-related information beyond a person’s or company’s core identity (see Identity Proofing / Verification), which can be important when evaluating risks or performing compliance assessments.

For example, you can use SSI for

employment background checks (education, work, criminal history)
financial due diligence (bank account information, liquidity events, credit ratings)
any other type of data verification required for transactions from insurance or health data to social proofs like ratings or recommendations.

Digital Credentials

SSI can be used to digitize any type of identity-related information in order to replace paper-based identity documents or cards with digital ones that are easier to manage, share and verify as well as harder to forge.

For example, think about official public sector documents such as identity certificates or about licenses or certificates that convey allowance to perform regulated activities.

You can find more examples in our White Papers:

Introduction to Self-Sovereign Identity
Me, Myself & (SS)I (co-authored by the Boston Consulting Group)

Identity Wallets

Any Questions

If you have any questions, feel free to get in touch.

Self-Sovereign Identity (SSI)

Learn about Self-Sovereign Identity (SSI).

Welcome to our Introduction to Self-Sovereign Identity (SSI) for developers and technical readers.

Before you get started, feel free to explore other (less technical) resources that will help you and your team to get a more holistic understanding of SSI and digital identity in general:

SSI | Basics

Learn what SSI is.

What is SSI?

Self-Sovereign Identity (SSI) is a user-centric approach to digital identity that gives people and organizations full control over their data. As a result, SSI enables anyone to easily share their data and reliably prove their identity (i.e. who they are and anything about them) without sacrificing security or privacy.

In other words, SSI enables you to “bring your own identity” and this is true for potentially any type of information - from your core identity (e.g. name, age, address) to your education and work records, your health and insurance data, bank account and financial information, etc.

Moreover, SSI can be used to model the digital identities of people, organizations and things.

At the end of the day, SSI promises a digital world in which interactions are effortless and worry-free. It is simply the next evolutionary step in identity management, a new paradigm in which our digital identities are no longer fragmented and locked into silos that are under someone else’s control, but only at our own disposal to be shared securely and privately.

How does SSI work?

SSI allows us to model digital identity just like we are used to the way identity works in the non-digital world based on paper documents and cards. There are just some minor twists.

For example, instead of our identity documents being made of paper or plastic, they are digital credentials made of bits and bytes and instead of storing them in wallets made of leather, they are stored in digital wallets on our phones. Importantly, these digital credentials can be reliably verified by anyone they are shared with online or offline.

In doing so, SSI enables decentralized ecosystems in which different parties can exchange and verify identity-related information. These ecosystems look like three-sided marketplaces, so that every party can take on three roles:

Issuers - Parties who “issue” identity-related data to people or organizations (“Holders”) in the form of digital credentials. They are the original data sources of an SSI ecosystem. For example, a government issues digital passports to citizens or a university issues digital diplomas to graduates.
Holders - Individuals or organizations who receive digital credentials that contain data about themselves from various sources (“Issuers”). By aggregating and storing such credentials in digital wallets, Holders can build holistic digital identities that are under their control and can easily be shared with third parties ("Verifiers").
Verifiers - Parties who rely on data to provide products and services can reliably verify and process data that has been provided by others (“Holders”). Verifiers, also called “Relying Parties”, are usually organizations or individuals in their professional capacity.

Usually, a single party plays only one of these roles per interaction. However, it is perfectly normal for a party to take on different roles in different interactions.

For example:

A university (Holder) is being accredited to issue certain types of educational credentials by a national authority (Issuer).
A university (Issuer) issues a digital diploma to a graduate (Holder), who can share this information with a recruiter (Verifier) in the course of a job application.
After the recruiting process, a recruiter (Issuer) issues the results of an applicant’s assessment (e.g. skills, referral) to the applicant (Holder), who can share this information with a new manager or another recruiter (Verifier).
A manager (Issuer) issues the results of a performance review to his employee (Holder) who can share this information with HR (e.g. to improve talent development programs).

Technologies & Concepts

Learn about the technologies and concepts on which SSI is based.

Understanding SSI requires the understanding of a few core concepts:

Registries, which hold a shared and trusted record of information. In other words, they represent a “layer of trust” and can be referred to as the “single source of truth”.
Cryptographic keys, which convey control over digital identities and enable core functionality such as encryption and authentication.
Decentralized Identifiers (DIDs), which give us the power of verifying information, for example credentials, anywhere, anytime, through the establishment of a public key infrastructure. They link keys to unique identifiers that allow different parties to find and interact with each other.
Verifiable Credentials (VCs) which are digital identity documents that can easily and securely be shared with and verified (incl. validity, integrity, authenticity, provenance) by anyone in a privacy preserving way. Importantly, they are never (!) stored on a blockchain due to privacy and compliance reasons.
Verifiable Presentations (VPs), contain identity data for verification from one or multiple VCs and are mainly created by the holder of the VCs.
Protocols enable the exchange of data (VCs) between different parties.
Wallets, which store our keys (control) and VCs (identity data) and enable the management and sharing of our digital identities and data via easy-to-use applications.

The SSI tech stack:

How the SSI works:

The following graphic shows how SSI works and highlights the core concepts (in blue)

Building Blocks:

Think of these core concepts as different building blocks that are available in different variations and can be put together in different ways:

As a result, there are different “flavours” of SSI depending on which variations of which building blocks have been used and how they have been put together.

Importantly, the differences in terms of technologies that are being used illustrate why interoperability has always been one of the most important topics within the industry and why the development and use of open standards (e.g. by the W3C, Decentralized Identity Foundation, OpenID Foundation and others) are vital for technology and vendor selection.

Registries

A shared and trusted record of information.

Registries serve as a single source of truth which all participants of an SSI ecosystem can trust. Depending on the ecosystem, registries make information accessible to anyone or just a limited group. Registries are important because they enable:

(Distributed) Public Key Infrastructures (DPKIs) which establishes an open distribution system for public keys which can be used for encryption and authentication among others.
Trust Registries hold reliable information about people, organizations, things and even credentials (e.g. data models, status and validity information) to ensure that different parties can trust each other and the identity-related data they exchange.

Different technologies can be used to implement Registries. For example:

Blockchains or L1: Typically blockchains are used because it is unfeasible (or even impossible) to tamper with them. The fact that no single organization can change the contents of a blockchain or manipulate the terms by which it is governed are very aligned with the requirements for identity ecosystems. Today, we see a growing number of developers and organizations focusing on so-called permissioned blockchains (i.e. only a selected group can “write”) like Ethereum Quorum/Enterprise. Permissionless blockchains, like Ethereum, are still used, but less than the permissioned alternatives for a variety of reasons like scalability, costs, lack of customisable governance frameworks.
L2: Layer two networks sit on top of blockchains and aggregate data before anchoring it. The main idea behind them is to circumvent common challenges of public, permissionless blockchains like scalability and cost issues. The most popular implementations in the context of identity are “ION” (for Bitcoin) and “Element” (for Ethereum).
Other Distributed Ledger Technologies (DLTs): Sometimes other DLTs are utilised like the Interplanetary File System (IPFS) though its use for digital identity remains limited.
Domain Name Service (DNS): Considering certain drawbacks of DLTs and their relatively slow adoption by the mass market, DNS can also be used to serve as a registry. Though it is not fully decentralised (considering its underlying governance framework), DNS has many advantages like its maturity and global adoption.

Importantly, SSI can be implemented without registries, particularly without blockchains, because identity data (or at least personal data of individuals) is never anchored due to privacy and compliance reasons. However, by combining SSI with blockchains (or other technologies), robust and trustworthy identity ecosystems that utilise transparent DPKIs and reliable Trust Registries can emerge.

Decentralised Identifiers (DIDs)

DIDs give us the power of verifying information, for example credentials, anywhere, anytime, through the establishment of a public key infrastructure.

DIDs are unique identifiers (URIs) which are standardised by the W3C. They can refer to any subject - from a person, to an organization, to a thing or basically anything else for that matter. Before we have a look at how a DID is structured and the benefit it provides, let's understand the shortcomings of current identifiers first and then see how the DID solves those.

The shortcomings of current IDs

In the digital economy, data exchange happens a lot, which makes it increasingly important to be able to identify persons, concepts or anything else for that matter in a secure and verifiable way.

A person today can have multiple different identifiers, like:

name@surname.com
https://www.surname.com
0000-0000-0000-0000 (ORCID based identifier, used to identify authors of scholarly communication)

All of these identifiers work, but none fulfills to be decentralized, persistent, resolvable and cryptographically verifiable when put into the following questions.

Is the identifier decentralized?

https://www.surname.comdepends on a single point of failure. What happens if the hosting side disappears?
0000-0000-0000-0000 (ORCID) depends on the ORCID database. What happens if it is discontinued, hacked, etc?

Is the identifier persistent?

https://www.surname.com If I do no longer pay for that domain, the identifier will be gone or even bought by somebody else.

Is the identifier resolvable?

How can I get additional information about 0000-0000-0000-0000 (ORCID) identifiers?

Is the identifier verifiable?

How can I prove that I own the domain, https://www.surname.com?
If I stopped paying for my domain, https://www.surname.com and somebody else would buy it. How would somebody know that the information provided on the side was actually mine?

All those problems make it hard to be 100% sure when exchanging information, that the party we are exchanging information with, is actually the party and not some malicious actor pretending to be the party.

DID to the rescue

The design of DIDs, which is a new form of unique identifier that has been standardized by the W3C, can now help us address these problems of current identifiers, by being:

Decentralized

The DIDs no longer depend on centralized registries, identity providers, authorities, etc.

Persistent

Once created, the did is permanently assigned to the subject.

Resolvable

It is possible to find a basic set of information when resolving the did. Typically, this will lead to a DID Document.

Cryptographically verifiable

There is a mechanism to cryptographically prove identity and ownership via information provided by the DID Document.

DID format:

The DID is a simple text string built up of three parts:

A variety of “DID methods'', which are different implementations of the DID specification, exist. Considering that DID methods differ in terms of how they are created, registered and resolved, different methods come with different advantages and disadvantages.

For example, while DIDs are often anchored on Registries, such as EBSI (did:ebsi) or the Domain Name Service (did:web), new methods emerged that do not require Registries because their distribution is based on peer-to-peer interactions (e.g. did:key).

Now we can take any did, look at the method and resolve it based on the framework around the method. The resolved content will most of the time be JSON or JSON-LD, although other data formats might also be added in the future. The resolved content is called DID Document.

DID Document

A container of information holding:

The Subject

The owner of the DID Document

The Controllers

The entities allowed to introduce changes to the DID Document. The controller may or may not be identical to the "subject". For example, if the DID Document belonged to a DID of a book. The controller would be the author or another related person, rather than the book itself.

Cryptographic data

The DID document contains the public keys of the corresponding entity. The keys might be of any algorithm (typically elliptical curve keys or RSA keys are used), and are mostly encoded in the JWK format. However, other encoding formats such as PEM or Multibase are also supported. The keys can be classified to be used in certain use cases such as: authentication, verification, etc.

Service endpoints

Services that the subject wants to mention

DID general flow

Example (did:ebsi)

The identifier did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y of the method ebsi would resolve to the following DID document:

{
    "@context": [
        "https://w3id.org/did/v1"
    ],
    // keys used for the authentication of the contoller
    "authentication": [
        "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y#1a7514b2d58141c3982021a6323b99bf"
    ],
    // the subject
    "id": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y",
    // the cryptographic data used for authentication, verification or other use cases
    // utilizing public keys
    "verificationMethod": [{
        "controller": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y",
        "id": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y#1a7514b2d58141c3982021a6323b99bf",
        "publicKeyJwk": {
            "alg": "EdDSA",
            "crv": "Ed25519",
            "kid": "1a7514b2d58141c3982021a6323b99bf",
            "kty": "OKP",
            "use": "sig",
            "x": "tqJADByHRU3YxswewQD4wQYXU9tB43j3PfjofsYEvqs"
        },
        "type": "Ed25519VerificationKey2018"
    }]
}

Our open source products enable you to use different DID methods for different identity ecosystems. Every relevant functionality (e.g. generation, anchoring, resolution) is supported .

Verifiable Credentials (VCs)

Verifiable Credentials (VCs) are digital credentials that contain actual identity data of people or organizations and are standardized by the W3C. They are digital equivalents of paper-based identity documents like passports or diplomas.

Before we dive deeper into Verifiable Credentials and learn about their structure and how they work, we will have a look at the problems of today's credentials.

Credentials today

Today's credentials are easy to fake, hard to verify, and not privacy preserving by design. Making it hard for business and people offline but especially online to trust each other, when exchanging information and data. This brings about many problems, thereunder:

To verify that a document or claim presented is actually valid, can take up many resources and time. Just think about, what you had to do last time you opened up a bank account. The presenting of your ID card via a video call, taking selfies etc.
Often the credentials provided by you to get access to a service, are then stored on centralized servers. This makes them not only vulnerable to data breaches, but you also need to trust the organization that they only use the data in ways you would agree with.
You might be forced to disclose more information than needed. The police officer checking your driver license, in most cases, only needs to know that you are allowed to drive, but not where you live or your name.
Organizations employing people who claim to have a skill by presenting a fake certificate, can get jobs, which, when performed poorly, could have catastrophic consequences.

This is why we need a better way to verify the claims presented, and that is where Verifiable Credentials come in.

Verifiable Credentials to the Rescue

With VCs and the standard introduced by W3C, we now have a way of creating a digital piece of information that identifies a particular entity or verifies a specific attribute, qualification or claim about them, in a way, that is almost impossible to forger, easy to verify, and privacy preserving by design. Leaving us with the following benefits:

Easy to verify: There is a clearly defined and reliable way of verifying a Verifiable Credential.
Temper-proof: No one expect the issuer (entity creating the VC) can change the claims stated in the VC.
Independent: No need to contact the issuer of the presented certificate to be certain about its validity. The check can happen in an independent, asynchronous way.
Data is owned: The holder of a certificate now owns the data and decides what to share and when, only providing proof but never actually giving it (a copy) to the service provider.
Portable: The user is free to choose where to take their VC and in which wallet it is saved.

The lifecycle of a Verifiable Credential

For us to understand the typical lifecycle of a Verifiable Credential, we need to make sure, we understand the idea behind an Issuer, Holder and Verifier and what DID and DID Documents are. With that out of the way, let's start with cycle.

Setup

Registration of the Issuer: Depending on the governance framework, the issuer will be accredited by a trusted entity, before their DID as well as DID Document will be put into the Registry. The Registry is the Single Source of truth and trust entity which verifiers will use as a reference point to make sure a presented VC is valid.
Holder setup: The holder generates the DID via the wallet and saves the private and public key as part of the DID Document, to be able to request, receive and present Verifiable Credentials from thereon. The DID and the DID Document will never be put into any registry, it will only exist locally in the wallet.
Verifier setup: The verifier only needs to have the technology to communicate with the registries when presented with a VC, to validate its authenticity using the DID and the DID Document from the issuer.

After the registration of the issuer and the setup of the wallet for the holder, the holder can now receive a VC from the issuer.

Issuance & Content

When the holder receives their Verifiable Credential it will be saved on their wallet, and it will contain the following:

Metadata:
- The DID of the issuer
- The status of the credential (expiration and issuing date, revoke state)
Claims:
- The DID of the holder of the credential
- The claims about the subject (what the issuer asserts about the subject). This could be, if they can drive a car and what type of car (driver license) or the subject of their study and knowledge areas skilled in (university certificate).
Proof:
- This will contain the signatures of the issuer, which can be used to see if the content of the VC has been tempered with and for an authenticity check.

Using the Certificate

The holder can now use the VC in their wallet to access services, and get access to products by presenting it to the service/product provider (The Verifier) and thereby making it a Verifiable Presentation. The verifier will go through the following steps to make sure the certificate is valid:

Before the validation of the content of the certificate can take place, the VC needs to be parsed from the support JSON-LD or the JWT format. Depending on the ecosystem used, there will also happen a validation of the schema of the credential.
Validate that the DID of the holder, stated in the certificate, is the person presenting the VC.
Checking if all the state values are valid (expiration date and if the certificate is revoked or not).
Checking the claims about the subject and if they match the requirements to give the person access to the service they are requesting to get access to.
Checking the signatures of the issuer and the holder, by getting the DID of the issuer from the registry and the DID from the holder in their wallet and validating it using the public keys presented in the related DID documents.

When all the checks pass, the verifier can now grant the holder access to the service requested.

Example of a Verifiable Credential

{
 // Sets the context of the credential. Establishes the idea and meaning behind the 
 // special terms used in the credential, so that the parties interacting with the
 // credential are on the same side.
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://essif.europa.eu/schemas/v-a/2020/v1",
    "https://essif.europa.eu/schemas/eidas/2020/v1"
  ],
  // The identifier of the Verifiable Credential
  "id": "education#higherEducation#3fea53a4-0432-4910-ac9c-69ah8da3c37f",
  // Types of the credential, giving you an overview of the data to expect
  "type": [
    "VerifiableCredential",
    "VerifiableAttestation"
  ],
  // Issuer of the credential
  "issuer": "did:ebsi:2757945549477fc571663bee12042873fe555b674bd294a3",
  // When the credential was issued
  "issuanceDate": "2019-06-22T14:11:44Z",
  // When the credential will be valid
  "validFrom": "2019-06-22T14:11:44Z",
  // Claims about the subject
  "credentialSubject": {
  // Identifier of the only subject of the credential
    "id": "id111"
  },
  // Current status of the credential, such as if it is suspended or revoked
  "credentialStatus": {
    "id": "https://essif.europa.eu/status/identity#verifiableID#1dee355d-0432-4910-ac9c-70d89e8d674e",
    "type": "CredentialStatusList2020"
  },
  // Used data schema by the credential. It gives the verifiers an idea, 
  // if the presented data in the credential conforms.
  "credentialSchema": {
    "id": "https://essif.europa.eu/tsr-vid/verifiableid1.json",
    "type": "JsonSchemaValidator2018"
  },
  // It can give the verifier an extra level of security, that the issued credential
  // can be trused, as it lays out requirements the issuer needs to check the 
  // subject against, before issuance of the credential can take place.
  "evidence": [
    {
      "id": "https://essif.europa.eu/tsr-va/evidence/f2aeec97-fc0d-42bf-8ca7-0548192d5678",
      "type": [
        "DocumentVerification"
      ],
      "verifier": "did:ebsi:2962fb784df61baa267c8132497539f8c674b37c1244a7a",
      "evidenceDocument": "Passport",
      "subjectPresence": "Physical",
      "documentPresence": "Physical"
    }
  ],
  // Digital proof that makes the credential temper-evident
  "proof": {
    // The cryptographic signature suite that was used to generate the signature
    "type": "EidasSeal2021",
    // The date when the signature was created
    "created": "2019-06-22T14:11:44Z",
    // Purpose of this prove
    "proofPurpose": "assertionMethod",
    // The identifier of the public key that can be used to verify the signature
    "verificationMethod": "did:ebsi:2757945549477fc571663bee12042873fe555b674bd294a3#2368332668",
    // The digital signature value
    "jws": "HG21J4fdlnBvBA+y6D...amP7O="
  }
}

Our open source products enable you to act as an "Issuer" (create and issue VCs), as a Holder (manage and share VCs/VPs) and as a Verifier (request and verify VCs/VPs).

Verifiable Presentations (VPs)

A Verifiable Presentation (VP) is a collection from one or more Verifiable Credentials, whereas the authorship of the whole collection can be cryptographically verified. VPs are standardized as part of the W3C Verifiable Credentials Data Model.

Why do we need Verifiable Presentations?

Verifiable Presentations, make it possible to combine and tamper-evident share data of one or more Verifiable Credentials. The shared presentation of the data will be encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. In situations where only a subset of the original Verifiable Credential data is reveled, for example, to enhance user privacy, Zero-Knowledge Proofs can help us keep that data verifiable.

How Verifiable Presentations are composed?

Verifiable Presentations represent a composition of claims, which can come from one or multiple Verifiable Credentials, of which the authorship is verified. This gives the holder of credentials the chance of composing context specify presentations, which only contain the data which is relevant in that context. When presenting the composition to a verifier, it can easily be validated.

Taking a closer look at how they are built up. We will see four different layers:

Presentation Layer - Being the Verifiable Presentation itself with the required metadata
Credential Layer - Referenced by Layer 1 and pointing to one or more credentials
Credential Proof Layer - Holding the proofs of the credentials and the signatures from Layer
Presentation Proof Layer - Holding the proof of the Verifiable Presentation and its signatures

Example of a Verifiable Presentation in code

If you want to get a better understanding of the different attributes present, please visit our section about VCs.

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "type": [
    "VerifiableCredential",
    "VerifiablePresentation"
  ],
  "verifiableCredential": [
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://essif.europa.eu/schemas/vc/2020/v1"
      ],
      "credentialSubject": {
        "id": "did:ebsi:00000004321",
        "naturalPerson": {
          "did": "did:example:00001111"
        }
      },
      "id": "did:ebsi-eth:00000001/credentials/1872",
      "issuanceDate": "2020-08-24T14:13:44Z",
      "issuer": "did:ebsi:000001234",
      "proof": {
        "created": "2020-08-24T14:13:44Z",
        "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19.",
        "proofPurpose": "assertionMethod",
        "type": "EcdsaSecp256k1Signature2019",
        "verificationMethod": "did:ebsi-eth:000001234#key-1"
      },
      "type": [
        "VerifiableCredential",
        "VerifiableAuthorization"
      ]
    },
    {
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://w3id.org/citizenship/v1"
      ],
      "credentialSubject": {
        "birthDate": "1958-08-17",
        "givenName": "JOHN",
        "id": "did:example:123",
        "type": [
          "PermanentResident",
          "Person"
        ]
      },
      "issuer": "did:example:456",
      "proof": {
        "created": "2020-04-22T10:37:22Z",
        "jws": "eyJjcml0IjpbImI2NCJdLCJiNjQiOmZhbHNlLCJhbGciOiJFZERTQSJ9..BhWew0x-txcroGjgdtK-yBCqoetg9DD9SgV4245TmXJi-PmqFzux6Cwaph0r-mbqzlE17yLebjfqbRT275U1AA",
        "proofPurpose": "assertionMethod",
        "type": "Ed25519Signature2018",
        "verificationMethod": "did:example:456#key-1"
      },
      "type": [
        "VerifiableCredential",
        "PermanentResidentCard"
      ]
    }
  ]
}

Our open source products enable you to act as a Holder (share VPs) and as a Verifier (request verify VPs).

Data Exchange (Protocols)

Data Exchange (Protocols) enable the exchange of data (VCs) between different parties.

Different authentication and data exchange protocols are used to securely transfer identity data (e.g. VCs, VPs) between parties (e.g. from an Issuer to a Holder). They typically establish a mutually authenticated and encrypted data channel between the communicating parties.

The most common data exchange protocols used for SSI are:

OIDC4SSI / SIOP (Self-Issued OpenID Connect Provider): An extension of a mature authentication and authorization protocol called "OpenID Connect" (OIDC).
DIDComm: A novel protocol specifically designed for SSI and maintained by the Decentralized Identity Foundation (DIF).
Credential Handler API: A proposed browser-extension that may be used to connect the user's identity wallet to a web-application.

Our solutions enable you to use different data exchange protocols like OIDC/SIOP as required by different ecosystems.

Getting started

Quick Start

Getting started with the SSI Kit.

Discontinuation Notice

Important: Please be informed that, beginning from December 2023, the SSI Kit will no longer receive new features. Furthermore, the SSI Kit is planned for discontinuation by the end of Q3 2024. However, all functionalities currently offered by the SSI Kit will be integrated into our new libraries, APIs, and apps under The Community Stack. This is aimed at providing a more modular, flexible, and efficient solution for your needs. For any clarification or queries, feel free to contact us as we aim to make this transition as smooth as possible.

The SSI-Kit's functionality can be used in a variety of ways. Select your preference to get started

Tutorials

My First Verifiable Credential (VC) - Issue and verify your first VC using the SSI-Kit Api
Advanced Verifiable Credentials (VC) - Leverage custom credential templates, the credential status property, prebuild and custom verification policies.

REST API

Manage keys, DIDs, issue Verifiable Credentials, and verify them using the SSI-Kit's REST API.

Installation & Running the Project

Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine

Pull the docker container directly from docker hub and run the project

docker run -p 7000-7004:7000-7004 -itv $(pwd)/data:/app/data waltid/ssikit serve -b 0.0.0.0

This will create a folder called data in your current directory as storage for the VC, DIDs, Keys and other things which need to be stored in order to provide all the functionality.

Clone the project

git clone https://github.com/walt-id/waltid-ssikit.git

2. Change the folder

cd waltid-ssikit/

3. Run the project

The first time you run the command you will be asked to built the project. You can confirm the prompt.

./ssikit.sh serve

If you want to get a more detailed overview of the options provided for building the project on your machine, please refer to building the project.

After successfully running the project, you will have the endpoints, described below, available for use.

Exposed endpoints:

Type

Locally

General Available

The Core API exposes most of the functionalities provided by the SSI Kit, however newer features will only be released in the other API endpoints. Therefore, it is recommended to use the Signatory API, Custodian API and Auditor API for most use cases.

Next Steps

Issuance - Learn how to issue credentials
Holders - Learn how to maintain secrets and sensitive data (e.g. keys, Verifiable Credentials)
Verifiers - Learn how to verify credentials

Tutorials

My First VC - Play through a whole use case from Issuance to Verification

Signatory API - For Issuers

Signatory REST API functions.

Swagger | Redoc

The Signatory API exposes the "issuance" endpoint, which provides flexible integration possibilities for anyone intending to act as an "Issuer" (i.e. create, sign and issue Verifiable Credentials), as follows:

Credentials - issue credentials
Templates - create and mange credential templates
Revocations - revocation related functions

Credentials

If you're new to VCs, check out the intro section for an overview.

The /v1/credentials/issue endpoint issues a specified credential.

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "templateId": "string",
    "config":
    {
        "issuerDid": "string",
        "subjectDid": "string",
        "verifierDid": "string",
        "issuerVerificationMethod": "string",
        "proofType": "JWT",
        "domain": "string",
        "nonce": "string",
        "proofPurpose": "string",
        "credentialId": "string",
        "issueDate": "2022-10-06T18:09:14.570Z",
        "validDate": "2022-10-06T18:09:14.570Z",
        "expirationDate": "2022-10-06T18:09:14.570Z",
        "dataProviderIdentifier": "string",
        "ldSignatureType": "string",
        "creator": "string",
        "ecosystem": "string",
        "statusType": "string"
    },
    "credentialData":
    {
        "additionalProp1":
        {},
        "additionalProp2":
        {},
        "additionalProp3":
        {}
    }
}

The issued credential displayed either in JSON-LD or JWT format

E.g. Issue a UniversityDegree credential in the default JSON-LD format. In case you don't have the DID for the Issuer and or the Holder, you can create one here.

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "UniversityDegree",
    "config":
    {
        "issuerDid": "did:web:walt.id",
        "subjectDid": "did:web:my.domain"
    },
    "credentialData":
    {
        "credentialSubject":
        {
            "degree":
            {
                "name": "Bachelor of Science and Arts",
                "type": "BachelorDegree"
            }
        }
    }
}'

{
    "templateId": "UniversityDegree",
    "config":
    {
        "issuerDid": "did:web:walt.id",
        "subjectDid": "did:web:my.domain"
    },
    "credentialData":
    {
        "credentialSubject":
        {
            "degree":
            {
                "name": "Bachelor of Science and Arts",
                "type": "BachelorDegree"
            }
        }
    }
}

{
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "credentialSubject":
    {
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        },
        "id": "did:web:my.domain"
    },
    "id": "urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270",
    "issued": "2022-10-07T09:53:41.369913097Z",
    "issuer":
    {
        "id": "did:web:walt.id"
    },
    "validFrom": "2022-10-07T09:53:41.369917079Z",
    "issuanceDate": "2022-10-07T09:53:41.369917079Z",
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "proof":
    {
        "type": "Ed25519Signature2018",
        "creator": "did:web:walt.id",
        "created": "2022-10-07T09:53:41Z",
        "domain": "https://api.preprod.ebsi.eu",
        "nonce": "dc2be572-cca4-43dc-9903-0fec1dcf786f",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..7EYkgjNRJ_hh0F5kONnPfrC4PLvg1g82czeANllDngsbk36a8lnHSlwersSqY0tdER4xIe7vbNVzi39C2DZTDQ"
    }
}

Check out the Issue with status section to learn about how to issue a verifiable credential with a credentialStatus property.

Templates

The currently available template functions are:

list - display the list of Templates
import - import a custom template
load - display the content of the template having the specified id

List templates

The /v1/templates endpoint returns the list of the available template ids

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates' \
  -H 'accept: application/json'

No parameter

[
    "string"
]

E.g. List the templates

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates' \
  -H 'accept: application/json'

[
    "DataSelfDescription",
    "VerifiableDiploma",
    "VerifiableVaccinationCertificate",
    "LegalPerson",
    "VerifiableAuthorization",
    "Europass",
    "KybMonoCredential",
    "KycCredential",
    "VerifiableMandate",
    "VerifiablePresentation",
    "EuropeanBankIdentity",
    "KybCredential",
    "VerifiableAttestation",
    "OpenBadgeCredential",
    "PeerReview",
    "DataConsortium",
    "ProofOfResidence",
    "AmletCredential",
    "ParticipantCredential",
    "PermanentResidentCard",
    "UniversityDegree",
    "VerifiableId",
    "DataServiceOffering",
    "GaiaxCredential",
    "Iso27001Certificate"
]

Import template

The /v1/templates/{id} endpoint to import your custom credential template

id path parameter (required) - id of the template, e.g. MyCustomCredential

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/templates/{id}' \
  -H 'accept: application/json'
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
  "type": [
    "VerifiableCredential",
    "MyCustomCredential"
  ],
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "string",
  "issuer": {
    "id": "string"
  },
  "issued": "2020-03-10T04:24:12.164Z",
  ... // custom data in json
}

{
  "type": [
    "VerifiableCredential",
    "MyCustomCredential"
  ],
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "issuer": {
    "id": "did:example:456"
  },
  "issued": "2020-03-10T04:24:12.164Z",
  "credentialSubject": {
    "id": "did:example:123",
    "firstName": "",
    "lastName": "",
    "country": "Austria"
  }
}

null

Load template

The /v1/templates/{id} endpoint displays the content of the template having the parameters:

id path parameter (required) - id of the template

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates/{id}' \
  -H 'accept: application/json'

No parameter

The template content as JSON

E.g. Load the template for the id set to UniversityDegree.

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates/UniversityDegree' \
  -H 'accept: application/json'

{
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "credentialSubject":
    {
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        },
        "id": "did:example:123"
    },
    "id": "http://example.gov/credentials/3732",
    "issued": "2020-03-10T04:24:12.164Z",
    "issuer":
    {
        "id": "did:example:456"
    },
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ]
}

Revocations

Refer to Credential Statuses section for more details on verifiable credential revocations.

Custodian API - For Holders

Custodian REST API functions.

Swagger | Redoc

The Custodian API provides management functions for maintaining secrets and sensitive data (e.g. keys, Verifiable Credentials) in a secure way:

Key
DID
Credentials

Key management

Key management functions include:

List - lists the available keys
Load - loads a key specified by its alias
Generate - generate a key using the specified algorithm
Import - imports a key
Delete - deletes a specific key
Export - exports public and private key parts (if supported by the underlying keystore)

List keys

The /keys endpoint lists the key available to the Custodian

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys' \
  -H 'accept: application/json'

No parameters

{
    "list":
    [
        {
            "algorithm": "string",
            "cryptoProvider": "string",
            "keyId":
            {
                "id": "string"
            },
            "keyPair": {},
            "keysetHandle": null
        }
    ]
}

E.g. List the available keys

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys' \
  -H 'accept: application/json'

{
    "list":
    [
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "e548f032cadf4145ab6886a57c2e87e6"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "e70e8fd8932043caa7c857c3b944d0e0"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "b50db0c1f73242b8bb0f2f6324e15ec3"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "8cc0b1707ea345ed83e479469d42aac2"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "did:key:z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu#z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "186a1e0a6d42459ba902724fe7643ed4"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "c5b11445be0e4d37863170df3328630b"
            },
            "keyPair": {},
            "keysetHandle": null
        }
    ]
}

Load key

The /keys/{alias} endpoint loads a key specified by its alias.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys/{alias}' \
  -H 'accept: application/json'

No parameters

{
    "algorithm": "string",
    "cryptoProvider": "string",
    "keyId":
    {
        "id": "string"
    },
    "keyPair": {},
    "keysetHandle": null
}

E.g. Load a key with id e548f032cadf4145ab6886a57c2e87e6

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys/e548f032cadf4145ab6886a57c2e87e6' \
  -H 'accept: application/json'

{
    "algorithm": "EdDSA_Ed25519",
    "cryptoProvider": "SUN",
    "keyId":
    {
        "id": "e548f032cadf4145ab6886a57c2e87e6"
    },
    "keyPair": {},
    "keysetHandle": null
}

Generate key

The /keys/generate endpoint generates a key using the specified algorithm.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "algorithm": "string",
    "cryptoProvider": "string",
    "keyId":
    {
        "id": "string"
    },
    "keyPair": {},
    "keysetHandle": null
}

E.g. Generate a key using the EdDSA_Ed25519 algorithm.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "keyAlgorithm": "EdDSA_Ed25519" }'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "algorithm": "EdDSA_Ed25519",
    "cryptoProvider": "SUN",
    "keyId":
    {
        "id": "8394ea7883bc4328a3f18b146b7e16bd"
    },
    "keyPair": {},
    "keysetHandle": null
}

Import key

The /keys/import endpoint imports a key (JWK or PEM format) to the underlying keystore.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The key string in JWK or PEM format

{
    "id": "string"
}

E.g. Import a public key specified in JWK format.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{"kty":"OKP","use":"sig","crv":"Ed25519","kid":"bc6fa6b0593648238c4616800bed7746","x":"YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU","alg":"EdDSA"}'

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

{
    "id": "bc6fa6b0593648238c4616800bed7746"
}

Delete key

The /keys/{id} deletes the specified as parameter:

id path parameter (required) - the key alias

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/keys/{id}' \
  -H 'accept: application/json'

No parameters

Code 200

E.g. Delete the key with id bc6fa6b0593648238c4616800bed7746

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/keys/bc6fa6b0593648238c4616800bed7746' \
  -H 'accept: application/json'

Export key

The /keys/export endpoint exports a key.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlias": "string",
    "format": "JWK",
    "exportPrivate": true
}

The key in the specified format, JWK or PEM

E.g. Export the public key with id = e548f032cadf4145ab6886a57c2e87e6 as JWK.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlias": "e548f032cadf4145ab6886a57c2e87e6",
  "format": "JWK",
  "exportPrivate": false
}'

{
    "keyAlias": "e548f032cadf4145ab6886a57c2e87e6",
    "format": "JWK",
    "exportPrivate": false
}

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "e548f032cadf4145ab6886a57c2e87e6",
    "x": "jT8YleOQnaABpZTnvId3WoID4Pia9Lex9OndqQ22Xxs",
    "alg": "EdDSA"
}

Did management

DID management functions enable the following:

List - lists the available DIDs
Load - loads a DID by the specified id
Delete - deletes a DID by the specified url
Create - creates a new DID
Resolve - resolves a DID to a document
Import - import a DID

For more info on DIDs, go here.

List DID

The /did endpoint lists the available DIDs.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did' \
  -H 'accept: application/json'

No parameters

The list of DID strings

E.g. List the available DIDs

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did' \
  -H 'accept: application/json'

[
    "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "did:web:my.domain",
    "did:web:walt.id",
    "did:key:z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu"
]

Load DID

The /did/{id} endpoint loads a DID specified by:

id path parameter (required) - the DID url string

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/{id}' \
  -H 'accept: application/json'

No parameters

{
    "assertionMethod":
    [
        "string"
    ],
    "authentication":
    [
        "string"
    ],
    "@context":
    [
        "string"
    ],
    "id": "string",
    "verificationMethod":
    [
        {
            "controller": "string",
            "id": "string",
            "publicKeyJwk":
            {
                "alg": "string",
                "crv": "string",
                "kid": "string",
                "kty": "string",
                "use": "string",
                "x": "string"
            },
            "type": "string"
        }
    ]
}

E.g Load the DID having the id = did:web:walt.id.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did/did%3Aweb%3Awalt.id' \
  -H 'accept: application/json'

{
    "assertionMethod":
    [
        "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4"
    ],
    "authentication":
    [
        "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:web:walt.id",
    "verificationMethod":
    [
        {
            "controller": "did:web:walt.id",
            "id": "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4",
            "publicKeyJwk":
            {
                "alg": "EdDSA",
                "crv": "Ed25519",
                "kid": "186a1e0a6d42459ba902724fe7643ed4",
                "kty": "OKP",
                "use": "sig",
                "x": "7-ofBq4vt0ePzC5IjiWkqTedfSv7WJJr6-HsQNXsr2M"
            },
            "type": "Ed25519VerificationKey2019"
        }
    ]
}

Delete DID

The /did/{id} deletes the DID specified by:

url - path parameter (required) - the DID url string

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/did/{id}' \
  -H 'accept: application/json'

No parameters

Code 200

E.g. Delete the DID having id = did:web:walt.id.

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/did/did%3Aweb%3Awalt.id' \
  -H 'accept: application/json'

Create DID

The /did/create endpoint creates a DID.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "method": "string",
    "keyAlias": "string",
    "method-dependent-options": "..."
}

The DID url string

The method and keyAlias properties are common for all did-method requests, method being required, while keyAlias - optional (if not specified, a new key will be automatically created using the default algorithm according to the did-method). The method-dependent options have default values, if not specified otherwise. Below are the available properties by did-method.

{
    "method": "key",
    "keyAlias": "string",
    "useJwkJcsPub": "boolean"
}

useJwkJcsPub (default) - false - specifies whether to create a did:key using the jwk_jcs-pub multicodec (code: 0xeb51)

{
  "method": "web",
  "keyAlias": "string",
  "didWebDomain": "string",
  "didWebPath": "string"
}

didWebDomain (default) - "walt.id"
didWebPath (default) - empty-string

{
    "method": "ebsi",
    "keyAlias": "string",
    "version": "int"
}

version (default) - 1

{
    "method": "cheqd",
    "keyAlias": "string",
    "network": "string"
}

network (default) - "testnet"

{
    "method": "iota",
    "keyAlias": "string"
}

{
    "method": "jwk",
    "keyAlias": "string"
}

E.g. Create a DID using the web method having the domain set to walt.id.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "web",
  "didWebDomain": "walt.id"
}'

{
    "method": "web",
    "didWebDomain": "walt.id"
}

did:web:walt.id

Resolve DID

The /did/resolve endpoint resolves a DID.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "did": "string"
}

{
    "assertionMethod":
    [
        "string"
    ],
    "authentication":
    [
        "string"
    ],
    "@context":
    [
        "string"
    ],
    "id": "string",
    "verificationMethod":
    [
        {
            "controller": "string",
            "id": "string",
            "publicKeyJwk":
            {
                "alg": "string",
                "crv": "string",
                "kid": "string",
                "kty": "string",
                "use": "string",
                "x": "string"
            },
            "type": "string"
        }
    ]
}

E.g. Reslove the DID having id = did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "did": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
}'

{
    "did": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
}

{
    "assertionMethod":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "authentication":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "capabilityDelegation":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "capabilityInvocation":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "keyAgreement":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6LShXhgLqK3vQX3eg18gwZUYNtt6M6FjPqpV1eQD86m8Hwh"
    ],
    "verificationMethod":
    [
        {
            "controller": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "publicKeyBase58": "6tW7uQ6c3YgZDoCFbHMB6QFjPENyHRouTUwGnLv36wS9",
            "type": "Ed25519VerificationKey2019"
        },
        {
            "controller": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6LShXhgLqK3vQX3eg18gwZUYNtt6M6FjPqpV1eQD86m8Hwh",
            "publicKeyBase58": "6rXWpXWBpwoJZHdNAJ3XDngQFCZ92nffc2viifTEQvAw",
            "type": "X25519KeyAgreementKey2019"
        }
    ]
}

Import DID

The /did/import endpoint resolves and imports the DID to the underlying data store.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The DID url string.

Code 201

E.g. Import DID having id = did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z'

did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z

Credentials management

The following functions are available for credentials management:

- lists the available credentials
- lists credential ids
- loads a credential by id
- store a credential
- delete a credential by id
- create a verifiable presentation from specific credentials
- create a verifiable presentation from specific stored credential ids

List credentials

The /credentials endpoint lists the available credentials:

id - query parameter (optional) - the list of credentials ids

E.g. List the the credentials having ids urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270 and urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84271

List credentials compact

The /credentials/list/credentialIds lists the available credentials ids.

E.g. List the available credentials ids.

Load credential

The /credentials/{id} loads a credential specified by:

id - path parameter (required) - the credential id

E.g. Load the credential having id = urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270.

Store credential

The /credentials/{alias} endpoint stores a verifiable credential by:

alias - path parameter (required) - the credential's id

The body should contain, the VC to be store. If no adjustments are required to VC, then the body can be the VC itself (e.g. the one received from the create VC endpoint).

E.g. Store the UniversityDegree verifiable credential.

Delete credential

The /credentials/{alias} deletes a credential by:

alias - path parameter (required) - the credential's id

E.g. Delete the credential with id = urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270

Present credential

The /credentials/present endpoint creates a verifiable presentation from the specified credentials.

E.g. Create a verifiable presentation from the provided VeriafiableID and OpenBadgeCredential credentials for a holder with did = did:web:my.domain.

Present stored credential

The /credentials/presentIds endpoint creates a verifiable presentation from the specified credential ids.

E.g. Create a verifiable presentation from the stored credential having id = urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270 for the holder with did = did:web:my.domain.

Auditor API - For Verifiers

Auditor REST API functions.

The Auditor API enables anybody to act as a "Verifier" (i.e. verify Verifiable Credentials or Verifiable Presentations). The validation steps can be easily configured by existing or custom policies.

The following functionality is available:

- credential / presentation verification
- policy related functions

Verification

The /v1/verify endpoint verifies a list of credentials / presentations specified in the JSON-LD format against a set of policies. Each of the policy should be registered with the Auditor before being used in the verification. If at least one of the listed policies fails the verification, then the entire credential is considered to be invalid.

E.g Verification of a UniversityDegree credential against Signature and JsonSchema policies, where SignaturePolicy is failing.

Policies

The Auditor Rest API also enables policy management with the following methods:

List policies

The /v1/policies endpoint lists the available verification policies. The policy id field is used to reference the policy during verification.

E.g. Listing of the verification policies

Create policy

The /v1/create/{name} creates a dynamic policy. The following parameters can be specified:

name path parameter (required) - specifies the value to be used as the policy id
update query parameter (optional, defualts to false) - accepts boolean values and specifies whether it should override an existing policy with the same name (only if the policy is mutable)
downloadPolicy query parameter (optional, defaults to false) - accepts boolean values and identifies the scope of the policy field:
- specifies a remote source that should be resolved to a policy
- specifies the actual policy content

E.g. Creating a Rego policy that checks if a credential subject id is not null or empty

Code 200

Delete policy

The /v1/delete/{name} endpoint deletes a dynamic policy. The following parameters can be specified:

name path parameter (required) - specifies the id value of the policy

Policy removed / Policy not found

E.g. Removing the policy having 'MyPolicy' name

Policy removed / Policy not found

Core API

Core REST API functions.

Swagger | Redoc

The Core API exposes wallet core functionality in the scope of storing and managing:

Cryptographic keys
Decentralised Identifiers (DIDs)
Verifiable Credentials (VCs)

Cryptographic keys

The following key management functions are available:

list - list of key ids
load - load the public key in JWK format
delete - delete key
generate - generate key
import - import key
export - export key

List key ids

The /v1/key endpoint lists the available key ids.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key' \
  -H 'accept: application/json'

No parameters

The list of key ids

E.g. List the available key ids.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key' \
  -H 'accept: application/json'

[
    "e548f032cadf4145ab6886a57c2e87e6",
    "e70e8fd8932043caa7c857c3b944d0e0",
    "b50db0c1f73242b8bb0f2f6324e15ec3",
    "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "8cc0b1707ea345ed83e479469d42aac2",
    "c5b11445be0e4d37863170df3328630b",
    "8394ea7883bc4328a3f18b146b7e16bd",
    "fd36a0159592413da1d89f192dd77dcd",
    "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
    "fa9296808e64440d89e6d245a1709141",
    "8dd54d6ae25a4818b1497530a8659dc1"
]

Load key

The /v1/key/{id} endpoint loads the public component of the provided key id in JWK format:

id - path parameter (required) - the key id

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key/{id}' \
  -H 'accept: application/json'

No parameters

The string for the public component of the key

E.g. Load the key having id = e548f032cadf4145ab6886a57c2e87e6.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key/e548f032cadf4145ab6886a57c2e87e6' \
  -H 'accept: application/json'

"{\"kty\":\"OKP\",\"use\":\"sig\",\"crv\":\"Ed25519\",\"kid\":\"e548f032cadf4145ab6886a57c2e87e6\",\"x\":\"jT8YleOQnaABpZTnvId3WoID4Pia9Lex9OndqQ22Xxs\",\"alg\":\"EdDSA\"}"

Delete key

The /v1/key/{id} endpoint deletes the specified key.

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/key/' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The key id string

Code 200

E.g. Delete the key having id = e548f032cadf4145ab6886a57c2e87e6.

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/key/' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'e548f032cadf4145ab6886a57c2e87e6'

e548f032cadf4145ab6886a57c2e87e6

Generate key

The /v1/key/gen generates a new key using the specified algorithm.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/gen' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "id": "string"
}

E.g. Generate a new key using the EdDSA_Ed25519 algorithm.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/gen' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlgorithm": "EdDSA_Ed25519"
}'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "id": "2251db0d15eb4e96b80c471edbaed185"
}

Import key

The /v1/key/import endpoint imports a key (JWK or PEM format) to the underlying keystore.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The key string in JWK or PEM format

{
    "id": "string"
}

E.g. Import a public key specified in JWK format.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{"kty":"OKP","use":"sig","crv":"Ed25519","kid":"bc6fa6b0593648238c4616800bed7746","x":"YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU","alg":"EdDSA"}'

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

{
    "id": "bc6fa6b0593648238c4616800bed7746"
}

Export key

The /v1/key/export endpoint exports public and private key part (if supported by underlying keystore).

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlias": "string",
    "format": "JWK",
    "exportPrivate": true
}

The key in the specified format, JWK or PEM

E.g. Export the public key with id = bc6fa6b0593648238c4616800bed7746 as JWK.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlias": "bc6fa6b0593648238c4616800bed7746",
  "format": "JWK",
  "exportPrivate": false
}'

{
    "keyAlias": "bc6fa6b0593648238c4616800bed7746",
    "format": "JWK",
    "exportPrivate": false
}

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

Decentralised-Identifiers

The following DID management functions are available:

list - list DIDs
load - load DID
delete by url - delete by DID url
create - create DID
resolve - resolve DID
import - import DID

List DIDs

The /v1/did endpoint lists the available DIDs.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/did' \
  -H 'accept: application/json'

No parameters

[
    "string"
]

E.g. List the available DIDs.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/did' \
  -H 'accept: application/json'

[
    "did:ebsi:zwdPobJGue3w86Gpqhq5Cni",
    "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
    "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "did:web:my.domain",
    "did:web:walt.id",
    "did:ebsi:zYubw2L8tCZSKKpAcMmCY2Q"
]

Load DID

The /v1/did/{id} endpoint loads a DID specified by:

id - path parameter (required) - the DID url string

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/did/{id}' \
  -H 'accept: application/json'

No parameters

The DID document

E.g. Load the DID = did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/did/did%3Akey%3Az6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z' \
  -H 'accept: application/json'

{
    "assertionMethod":
    [
        "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z"
    ],
    "authentication":
    [
        "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z"
    ],
    "capabilityDelegation":
    [
        "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z"
    ],
    "capabilityInvocation":
    [
        "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
    "keyAgreement":
    [
        "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6LSrs5FudTTsAUhHUoS1kzkhskwAWaYjyU13CVgZT7fwDWk"
    ],
    "verificationMethod":
    [
        {
            "controller": "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
            "id": "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
            "publicKeyBase58": "7g7ZKyYMckYQyVVZmBaRMR1j2Fj9m5biSwV7iz3HxeGc",
            "type": "Ed25519VerificationKey2019"
        },
        {
            "controller": "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
            "id": "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6LSrs5FudTTsAUhHUoS1kzkhskwAWaYjyU13CVgZT7fwDWk",
            "publicKeyBase58": "GBu6PKebmhkxC6RfV7UoPHYTKN3S3NHrADn14zU9Dqjz",
            "type": "X25519KeyAgreementKey2019"
        }
    ]
}

Delete DID

The /v1/did/{id} endpoint deletes the DID by:

id - path parameter (required) - the DID url string

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/did/{id}' \
  -H 'accept: application/json'

No parameters

Code 200

E.g. Delete the DID = did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z.

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/did/did%3Akey%3Az6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z' \
  -H 'accept: application/json'

Create DID

The /v1/did/create creates a DID.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "method": "string",
    "keyAlias": "string",
    "method-dependent-options": "..."
}

The DID url string

{
    "method": "key",
    "keyAlias": "string",
    "useJwkJcsPub": "boolean"
}

useJwkJcsPub (default) - false - specifies whether to create a did:key using the jwk_jcs-pub multicodec (code: 0xeb51)

{
  "method": "web",
  "keyAlias": "string",
  "didWebDomain": "string",
  "didWebPath": "string"
}

didWebDomain (default) - "walt.id"
didWebPath (default) - empty-string

{
    "method": "ebsi",
    "keyAlias": "string",
    "version": "int"
}

version (default) - 1

{
    "method": "cheqd",
    "keyAlias": "string",
    "network": "string"
}

network (default) - "testnet"

{
    "method": "iota",
    "keyAlias": "string"
}

{
    "method": "jwk",
    "keyAlias": "string"
}

E.g. Create a DID using the key method and automatically generate a new key.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "key"
}'

{
    "method": "key"
}

did:key:z6MkqJfAPYYDiDeNERPMufpS1gxgzqiG5fvQnqbYTwY5xJDE

Resolve DID

The /v1/did/resolve resolves a DID url string to a DID document.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "did": "string"
}

The DID document

E.g. Resolve the DID = did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "did": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
}'

{
    "did": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
}

{
    "assertionMethod":
    [
        "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
    ],
    "authentication":
    [
        "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
    ],
    "capabilityDelegation":
    [
        "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
    ],
    "capabilityInvocation":
    [
        "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa",
    "keyAgreement":
    [
        "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6LSkSwxKk6TFYcqcRHv7ALR87CTFK6bSkQsxwqczx1YgYik"
    ],
    "verificationMethod":
    [
        {
            "controller": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa",
            "id": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa",
            "publicKeyBase58": "CKK9rn4QHwPsXpjzSKGepGytPxcZZqpdGDmZAja4HchC",
            "type": "Ed25519VerificationKey2019"
        },
        {
            "controller": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa",
            "id": "did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa#z6LSkSwxKk6TFYcqcRHv7ALR87CTFK6bSkQsxwqczx1YgYik",
            "publicKeyBase58": "9mmnoSHbA5u6X2v9aWpToWyyQAZUk9Ej5y7wWVN1yAwz",
            "type": "X25519KeyAgreementKey2019"
        }
    ]
}

Import DID

The /v1/did/import endpoint resolves and imports the specified DID url to the underlying data store.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The DID url string

Code 201

E.g. Import the DID = did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa'

did:key:z6MkqmaCT2JqdUtLeKah7tEVfNXtDXtQyj4yxEgV11Y5CqUa

API Serving Configs

To expose the API service using the CLI tool or the docker container, use one of the following commands:

Show all options for specifying bind address and ports:

./ssikit.sh serve --help
docker run -itv $(pwd)/data:/app/data -p 192.168.0.1:7000-7003:7000-7003 ssikit serve --help

On localhost only using the default ports 7000-7003

./ssikit.sh serve

Binding on all network interfaces, using the default ports 7000-7003

./ssikit.sh serve -b 0.0.0.0

docker run -itv $(pwd)/data:/app/data -p 7000-7003:7000-7003 ssikit serve -b 0.0.0.0

Binding on a specific network interface (e.g.: 192.168.0.1)

./ssikit.sh serve -b 192.168.0.1

Using docker one needs to bind to 0.0.0.0 in the container and limit the binding from outside using the docker run -p syntax like so:

docker run -itv $(pwd)/data:/app/data -p 192.168.0.1:7000-7003:7000-7003 ssikit serve -b 0.0.0.0

Use custom ports by using the -p (Core API), -e (ESSIF API), -s (Signatory API) command options

./ssikit.sh serve -p 8000 -e 8001 -s 8002

docker run -itv $(pwd)/data:/app/data -p 8000-8002:8000-8002 ssikit serve -b 0.0.0.0 -p 8000 -e 8001 -s 8002

Dependency (JVM)

The SSI Kit can also be used as direct dependency for JVM-based applications. In this case an existing application can easily be enhanced with SSI functionality.

Dependency

The following illustrates how the SSI Kit can be used via Gradle or Maven (look for the current version on GitHub https://github.com/walt-id/waltid-ssikit)

Gradle

implementation("id.walt:waltid-ssikit:VERSION")

Maven

  <dependency>
        <groupId>id.walt</groupId>
        <artifactId>waltid-ssikit</artifactId>
        <version>VERSION</version>
   </dependency>

Required Maven repos:

https://maven.walt.id/repository/waltid/
https://maven.walt.id/repository/waltid-ssi-kit/

You can find the latest version here. Make sure when adding the version you add it without the 'v' in front.

Examples

CLI | Command Line Interface

Manage keys, DIDs, issue Verifiable Credentials, and verify them using the SSI-Kit command line tool.

Installation & Running the Project

Choose between a Docker or a JVM-based runtime.

Make sure you have Docker build environment installed on your machine.

Pulling the project directly from DockerHub

docker pull waltid/ssikit

2. Setting and alias for convenience

alias ssikit="docker container run -p 7000-7004:7000-7004 -itv $(pwd)/data:/app/data docker.io/waltid/ssikit"

3. Getting an overview of the commands and options available

ssikit -h

Make sure you have a JDK 16+ build environment including Gradle installed on your machine.

Clone the project

git clone https://github.com/walt-id/waltid-ssikit.git

2. Change the folder

cd waltid-ssikit/

3. Run the project

The first time you run the command you will be asked to built the project. You can confirm the prompt.

./ssikit.sh -h

You will now see an overview of all the different commands and options available.

4. Set an alias

To make it more convient to use, you can also set an alias as follows for the wrapper script:

alias ssikit="./ssikit.sh"

5. Get the overview again

ssikit -h

If you want to get a more detailed overview of the options provided for building the project on your machine, please refer to building the project.

Response configuration

For debug infos add "-v" e.g.:

ssikit -v

ssikit -v did create

Getting Started

Explore the components of the SSI Kit and their functionality:

Key Management
Decentralized Identifiers
Verifiable Credentials
OpenID Connect (OIDC)

Key Management

Key management functions like generation, listing, export/import, and deletion.

SSI-Kit CLI key management commands can be accessed with the key command. It provides the following functionality:

Generate key - using gen command
List keys - using list command
Import key - using import command
Export key - using export command
Delete key - using delete command

All commands have the help option available:

<your-command> -h
or <your-command> --help

E.g. key gen -h

Generate key

Use the gen command to create asymmetric key pair by the specified algorithm. Supported algorithms are:

RSA:
- key gen -a RSA
- or key gen --algorithm RSA
ECDSA Secp256k1:
- key gen -a Secp256k1
- or key gen --algorithm Secp256k1
EdDSA Ed25519 (default)
- key gen
- or key gen -a Ed25519
- or key gen --algorithm Ed25519

The returned value represents the keyId of the newly created key.

E.g. key gen -a Secp256k1

List keys

Use the list command to list all keys in the key store:

key list

It will output the following fields:

key index - index within the list
keyId - key identification number
key algorithm - algorithm used to create the key
crypto service - the cryptographic service used to create the key

Import key

Use the import command to import a key in JWK or PEM format:

key import <your-key-file-path>
- JWK - based on the JWK key ID and key material, an internal key object will be created and placed in the corresponding key store
- PEM - if there's no key ID in the PEM file (which is usually the case), a random key ID will be generated and, based on the key material, an internal key object will be created and placed in the corresponding key store. PEM files must have the file extension 'pem':
  - RSA keys - file should contain either the private key or private and public keys concatenated with a 'new line' character
  - Ed25519, Secp256k1 - file should contain both private and public keys concatenated with a 'new line' character

E.g.

Ed25519 JWK public key

key import ./ed25519jwk.json

Secp256k1 PEM key

key import ./secp256k1.pem

Export key

Use the export command to export a specified key type with the specified id and format.

Available key type:

public (default):
- key export <your-key-id>
- or key export <your-key-id> --pub
private:
- key export <your-key-id> --priv

Available export formats:

JWK (default):
- key export <your-key-id>
- or key export <your-key-id> -f JWK
- or key export <your-key-id> --key-format JWK
PEM:
- key export <your-key-id> -f PEM
- key export <your-key-id> --key-format PEM

The output will display the exported key in the specified format.

E.g.

key export 17592087c6f04c358b9b813dbe2ef027 --pub -f PEM

key export 17592087c6f04c358b9b813dbe2ef027 --pub

key export 17592087c6f04c358b9b813dbe2ef027 --priv -f PEM

key export 17592087c6f04c358b9b813dbe2ef027 --priv

Delete key

Use the delete command to delete a key with the specified ID:

key delete <your-key-id>

E.g. key delete 17592087c6f04c358b9b813dbe2ef027

Decentralized Identifiers

DID related operations, like registering, updating and deactivating DIDs. For more info on DIDs, go here.

Commands:

Create DID - using create command.
Resolve DID - using resolve command.
List DIDs - using list command.
Import DID to custodian store - using import command.
Delete DID from custodian - using delete command.

All commands have the help option available:

<your-command> -h
<your-command> --help

E.g. did create -h

Create DID

Creates a DID document using did create [options] command based on the corresponding SSI ecosystem (DID method). Optionally the associated asymmetric key is also created.

Options

-m, --did-method [key | web | ebsi | iota | jwk | cheqd] - Specify DID method [key], Supported DID methods are: "key", "web", "ebsi", "iota", "jwk"
-k, --key TEXT - Specific key (ID or alias)
-d, --domain TEXT - Domain for did:web
-p, --path TEXT - Path for did:web
-v, --version INT - Version of did:ebsi. Allowed values: 1 (default), 2
-n, --network [testnet | mainnet] - cheqd network, default is testnet
-j, --useJwkJcsPub - specifies whether to create a did:key using the jwk_jcs-pub multicodec (code: 0xeb51)

The returned value represents the DID document.

E.g. did create -m ebsi -k 8a2c3628acdd45999b4c0b5a69911437

IOTA support

For creating IOTA DIDs and registering them on the IOTA tangle, a wrapper library needs to be installed and available in the local library path.

The wrapper library is included in the SSIKit Docker image, such that for Docker users no additional setup is required.

CLI users can find instructions for build and SSIKit integration at:

https://github.com/walt-id/waltid-iota-identity-wrapper

Resolve DID

Resolves the DID document.

Options:

-d, --did TEXT DID to be resolved

-r, --raw / -t, --typed

-w, --write

List DIDs

List all created DIDs using did list command

Import DID

Import DID to custodian store using did import [options] command

Options

-k, --key-id TEXT - Specify key ID for imported did, if left empty, only public key will be imported
-f, --file TEXT - Load the DID document from the given file
-d, --did TEXT - Try to resolve DID document for the given DID

Delete DID

Use the delete command to delete a DID:

did delete <your did>

E.g. did delete -d "did:ebsi:zs79GYJvzEnQYxkAAj4UX1j"

Verifiable Credentials

VC related operations like issuing, verifying and revoking VCs.

VC related operations like issuing, verifying and revoking VCs. If you're new to VCs, check out the intro section for an overview.

Commands:

Issues and save VC - using issue command
Present VC - using present command
Verify VC or VP - using verify command
List verification policies - using policies command
Import VC to custodian store - using import command
VC templates - using templates command
List VCs - using list command

All commands have the help option available:

<your-command> -h
or <your-command> --help

E.g. vc issue -h

Issue and save VC

Use the issue command to issue a W3C Verifiable Credential with either a JWT or a JSON_LD signature.

options:

-t, --template TEXT specify the VC template. To create your own template, have a look here [Required]
-i, --issuer-did TEXT DID of the issuer (associated with signing key). [Required]
-s, --subject-did TEXT DID of the VC subject (receiver of VC). [Required]
-v, --issuer-verification-method TEXT KeyId of the issuers' signing key
-y, --proof-type [JWT|LD_PROOF] Proof type to be used [LD_PROOF]
-p, --proof-purpose TEXT Proof purpose to be used [assertion]
--interactive Interactively prompt for VC data to fill in
--ld-signature, --ld-sig \[Ed25519Signature2018|Ed25519Signature2020|EcdsaSecp256k1Signature2019|RsaSignature2018|JsonWebSignature2020|JcsEd25519Signature2020]
--ecosystem \[DEFAULT|ESSIF|GAIAX|IOTA] Specify ecosystem, for specific defaults of issuing parameters
--statusType \[StatusList2021Entry|SimpleCredentialStatus2022] specify the credentialStatus type

e.g.

vc issue -t OpenBadgeCredential -s did:key:z6MkpuUYdpaZPcpnEWnkE8vb7s2u2geTZJden1BwGXsdFUz3 -i did:ebsi:zZ5apnsHPUXNqjWELjNZhYW, returns a credential document (JSON format)

Present VC

Use present command to present a VC or VP to a verifier.

-i, --holder-did TEXT DID of the holder (owner of the VC)

-v, --verifier-did TEXT DID of the verifier (recipient of the VP)

-d, --domain TEXT Domain name to be used in the LD proof

-c, --challenge TEXT Challenge to be used in the LD proof

Verify VC or VP

use verify command to verify

-p, --policy VALUE Verification policy. Can be specified multiple times. By default, SignaturePolicy is used. For more details on how to specify the policies, refer to Verification Policies.

List verification policies

To see available verification policies, use vc policies command

Import VC to custodian store

VC templates

Learn about VC template related functions like the listing and exporting of templates, as well as how to create/import your own custom VC template.

List VC templates in custodian store

list List VC Templates.

vc template list result

Export VC template from custodian store

export <template-name> Export VC Template.

Options:

-n, --name <Name> Name of the template

e.g. vc templates export --name VerifiableId

Import VC template to custodian store

import <customCredentialPath.json>

Options:

-n, --name <Name> Name of the template

Arguments:

credential path the last argument of the command references the path to the custom credential, which should be imported

e.g vc templates import -n MyCustomCredential custom.json

custom.json

{
  "type": [
    "VerifiableCredential",
    "MyCustomCredential" // name of the credential
  ],
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "issuer": {
    "id": "did:example:456"
  },
  "issued": "2020-03-10T04:24:12.164Z",
  "credentialSubject": { //custom credential subject
    "id": "",
    "firstName": "",
    "lastName": "",
    "country": "Austria"
  }
}

Output of the command

List VCs

list VCs saved in the custodian store

e.g. vc list

OpenID Connect (OIDC)

OIDC for verifiable presentation and credential issuance

OIDC commands, related to credential presentation and credential issuance through OIDC SIOPv2 specifications

Commands:

ci OIDC for Credential Issuance
vp OIDC for Verifiable Presentations

Examples

Building the Project

For building the project Gradle 7 as well as JDK 16 (or above) is required.

Docker Build

Downloading the Project

First clone the Git repo and switch into the project folder:

git clone https://github.com/walt-id/waltid-ssikit.git
cd waltid-ssikit/

Docker Container

Building the Docker Container

./ssikit.sh build-docker

or with Podman

./ssikit.sh build-podman

or without script

docker build -t ssikit .

Manually

podman build -t ssikit .

Docker Compose

Run as RESTful service via Docker Compose:

docker-compose build
docker-compose up

Local Build

For building the project JDK 16+ is required.

Downloading the Project

First clone the Git repo and switch into the project folder:

git clone https://github.com/walt-id/waltid-ssikit.git
cd waltid-ssikit/

Wrapper

The walt.id wrapper script ssikit.sh is a convenient way for building and using the library on Linux.

./ssikit.sh {build|build-docker|build-podman|extract|execute (default)}

The script takes one of the the following arguments:

build|build-docker|build-podman|extract|execute.

For example, for building the project, simply supply the "build" argument:

./ssikit.sh build

Gradle

Manually with Gradle:

gradle clean build

After the Gradle build you can run the executable.

In build/distributions/ you have two archives, a .tar, and a .zip.

Extract either one of them, and run waltid-ssi-kit-1.0-SNAPSHOT/bin/waltid-ssi-kit.

cd build/distributions
tar xf waltid-ssi-kit-1.0-SNAPSHOT.tar    # or unzip for the .zip
cd ../..  # go back to the root-directory

./build/distributions/waltid-ssi-kit-1.0-SNAPSHOT/bin/waltid-ssi-kit

Project Configurations

Services come with their own configuration files.

For the configuration of service -> implementation mappings, ServiceMatrix is used.

The default mapping file is "service-matrix.properties", and looks like this:

id.walt.services.vc.VCService=id.walt.services.vc.LetstrustVCService
id.walt.services.crypto.CryptoService=id.walt.services.crypto.SunCryptoService
id.walt.services.keystore.KeyStoreService=id.walt.services.keystore.SqlKeyStoreService
id.walt.services.key.KeyService=id.walt.services.key.WaltIdKeyService

e.g., to change the keystore service, simply replace the line

id.walt.services.keystore.KeyStoreService=id.walt.services.keystore.SqlKeyStoreService

with your own implementation mapping, e.g. for the Azure HSM keystore:

id.walt.services.keystore.KeyStoreService=id.walt.services.keystore.azurehsm.AzureHSMKeystoreService

To add a service configuration:

id.walt.services.keystore.KeyStoreService=id.walt.services.keystore.SqlKeyStoreService:sql.conf Service configuration is by default in HOCON format. Refer to the specific service on how their configuration is laid out.

Demo

The demo shows an end-to-end SSI use case from the perspective of an individual (Holder).

Issuer Portal: Shows issuance of Verifiable Credentials (VCs) to a Holder’s wallet.

Visit our Issuer Portal.
Click on "Sign in". You do not need to input an email or a password.
Select and "confirm" your Verifiable Credential (VC) claim.

Wallet: Shows the receipt and management of VCs by a Holder.

Log into the Web Wallet (after being redirected from the Issuer Portal). The demo does not require the account-creation nor a valid passord. Just type a email address to log in you demo account.
Accept the connection request (from the Issuer Portal), by clicking on "share".
Review and accept the Verifiable Credential (VC).

Verifier Portal: Shows the presentation of VCs by Holder in order to authenticate or identify towards a Relying Party (Verifier).

Our hosted demo verifier is currently not working with our wallet. We are working on fixing the issue. Please reach out in case of any questions.

Visit the Verifier Portal.
Connect the wallet to share VCs.
Log into the wallet (you used before)
Accept the credential request by the Verifier.
Get access to the Verifier’s products, services or other benefits..

Ecosystems

EBSI

This section shows how you can use the SSI Kit to interact with Europe’s emerging identity ecosystem based on the

EU Blockchain Service Infrastructure (EBSI)
EU Self-Sovereign Identity Framework (ESSIF)

Here **** you can find examples on how to use the SSI Kit command line interface to interact with the EBSI/ESSIF ecosystem.

State of the EBSI/ESSIF specifications

Note, that some of the flows are not in their final version. Slight modifications are to be expected.

ESSIF DID Registration

Creation and anchoring of a new DID on the EBSI ledger (incl. use of "Verifiable Authorizations" and EBSI access tokens).

For SSIKit usage examples, refer to: EBSI DID registration

ESSIF Onboarding

Onboarding of a legal entity to the EBSI/ESSIF ecosystem (incl. combined VC request and DID registration).

EBSI Auth API

Gaining access to protected EBSI/ESSIF services (incl. presentation of "Verifiable Authorization").

Issuance of Verifiable Credentials

The ESSIF protocol for issuance of verifiable credentials aims to being compliant with the OIDC for credential issuance specification. Refer to the respective section for details:

OIDC for credential issuance

Exchange of Verifiable Presentations

The ESSIF protocol for presentation of verifiable credentials to a Verifier or Relying Party, aims to being compliant with the OIDC/SIOPv2 specification. Refer to this section for details:

OIDC/SIOPv2 for verifiable presentations

Code examples

Several code-examples how to use the ESSIF functionality of the SSI Kit are shown on GitHub

Basics

EU Blockchain Service Infrastructure (EBSI)

EBSI is a blockchain run by member states and public authorities. The idea is to create a trusted, public ledger that serves as a single source of truth for vital information. As such, EBSI instantiates different Trust Registries, such as

Trusted Issuers Registry (TIR), which contains information about organisations (e.g. public keys, accreditations, legal name, ...)
Trusted Accreditation Organisation Registry (TAOR), which is similar to the TIR, but contains information about organisations that can authorise Issuers to issue credentials in regulated fields.
Trusted Schemas Registry (TSR), which contains information about semantic contexts and vocabularies, policies and templates of VCs and their data models to ensure semantic interoperability.

European Self-Sovereign Identity Framework (ESSIF)

ESSIF's goal is to bring SSI to Europe. To do so, it fullfills different functions:

Governance and Trust Framework: ESSIF drives the creation of a EU Governance and Trust Framework supported by Member States.
Standards and specifications: ESSIF creates business, functional and technical specifications, which make up the European “flavor of SSI”.
Facilitate Adoption: ESSIF coordinates the adoption of SSI across Europe starting with pilot projects of “Early Adopters” which are public authorities from different member states.

Note that ESSIF specifies its own DID Method and different types of Verifiable Credentials (VCs):

Verifiable IDs, which are mainly used to identify entities at a high-level of assurance. As such, they can be compared to passports or national IDs.
Verifiable Attestions, which encode basically any other type of identity information, such as education or work records, financial data or health data.
Verifiable Manadates, which enable delegation as outlined in this paper.

There are also other variations of VC that evolved over time such as Verifiable Accreditations (as issued by TAOS; see above) or Verifiable Authorizations (used to authorize parties to interact with EBSI).

Use Cases & Flow Diagrams

Note, that EBSI/ESSIF specifications are evolving, which means that some flows are not available in their final version. Modifications are to be expected.

ESSIF DID Registration

Creation and anchoring of a new DID on the EBSI ledger (incl. use of "Verifiable Authorizations" and EBSI access tokens).

For SSIKit usage examples, refer to: EBSI DID registration

ESSIF Onboarding

Onboarding of a legal entity to the EBSI/ESSIF ecosystem (incl. combined VC request and DID registration).

EBSI Auth API

Gaining access to protected EBSI/ESSIF services (incl. presentation of "Verifiable Authorization").

Issuance of Verifiable Credentials

The ESSIF protocol for issuance of verifiable credentials aims to being compliant with the OIDC for credential issuance specification. Refer to the respective section for details:

OIDC for credential issuance

Exchange of Verifiable Presentations

The ESSIF protocol for presentation of verifiable credentials to a Verifier or Relying Party, aims to being compliant with the OIDC/SIOPv2 specification. Refer to this section for details:

OIDC/SIOPv2 for verifiable presentations

Code examples

Several code-examples how to use the ESSIF functionality of the SSI Kit are shown on GitHub

Command line interface

ESSIF specific operations.

Commands:

onboard ESSIF Onboarding flow
auth-api ESSIF EBSI Authentication flow
did ESSIF DID operations.
tir ESSIF Trusted Issuer Registry operations.
timestamp EBSI Timestamp API operations.
taor ESSIF Trusted Accreditation Organization operations.
tsr ESSIF Trusted Schema Registry operations

DID Registration

Usage / examples

The following subsections show examples of interactions with the EBSI/ESSIF frameworks using the SSI Kit command line interface, REST APIs and library SDK.

You can find more information about EBSI/ESSIF here.

Onboarding & DIDs

This use case describes the steps, which are required to register a DID on the EBSI blockchain.

CLI

Key generation (type ECDSA Secp256k1, which is required for signing ETH transactions)

./ssikit.sh key gen -a Secp256k1
=> keyId: 7db4b285984640d485842c0b1ccdcf92

Generation of the DID document

./ssikit.sh did create -m ebsi -k 7db4b285984640d485842c0b1ccdcf92
=> DID: did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg

EBSI/ESSIF Onboarding flow.

As prerequisite, the bearer token (validity of 15 min) from https://app-pilot.ebsi.eu/users-onboarding/v2 must be placed in file data/ebsi/bearer-token.txt

./ssikit.sh essif onboard --did did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg

After successfully completing the onboarding process, the Verifiable Authorization (validity of 6 months) from the Ebsi Onboarding Service is placed in data/ebsi/verifiable-authorization.json

EBSI/ESSIF Auth API flow

./ssikit.sh essif auth-api --did did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg

After successfully completing the Auth API flow, the decrypted EBSI Access Token (validity of 15min) can be accessed in file: /home/pp/dev/walt/data/ebsi/ebsi_access_token.json

EBSI/ESSIF DID registration

./ssikit.sh essif did register --did did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg

DID Resolution (only to check if the DID was correctly anchored with the EBSI blockchain)

./ssikit.sh did resolve --did did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg

The resulting DID document from the EBSI blockchain:

{
  "authentication": [
    "did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg#7db4b285984640d485842c0b1ccdcf92"
  ],
  "@context": [
    "https://w3id.org/did/v1"
  ],
  "id": "did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg",
  "verificationMethod": [
    {
      "controller": "did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg",
      "id": "did:ebsi:241ou8rtrYnBokFALv3PGFeTRYQuLdyZnpFk3wFFhhiDKdLg#7db4b285984640d485842c0b1ccdcf92",
      "publicKeyJwk": {
        "alg": "ES256K",
        "crv": "secp256k1",
        "kid": "7db4b285984640d485842c0b1ccdcf92",
        "kty": "EC",
        "use": "sig",
        "x": "wpFN5Pi6v3MiM6B5Awd4lqZk1usQQDDUAvVNXqXp4uw",
        "y": "iHVFCdaeIYbZheeQOtBCUpWCtoQhfPCx5N5MQuhbEFo"
      },
      "type": "Secp256k1VerificationKey2018"
    }
  ]
}

REST API

First pull the latest container

docker pull waltid/ssikit

Starting the container as RESTful service

docker run -itv $(pwd)/data:/app/data -p 7000-7004:7000-7004 waltid/ssikit -v serve -b 0.0.0.0

Key generation (type ECDSA Secp256k1, which is required for signing ETH transactions)

curl -X POST "http://127.0.0.1:7000/v1/key/gen" -H  "accept: application/json" -H  "Content-Type: application/json" -d "{\"keyAlgorithm\":\"ECDSA_Secp256k1\"}"

Generation of the DID document

curl -X POST "http://127.0.0.1:7000/v1/did/create" -H  "accept: text/plain" -H  "Content-Type: application/json" -d "{\"method\":\"ebsi\",\"keyAlias\":\"751da5b181e64475a811a374ae1a6923\"}"
=>  did:ebsi:22tCpv2yh4EJLm6o18JiS2AebaQAL6QcHH83mS6Cz94QumtY

EBSI/ESSIF Onboarding flow

curl -X POST "http://127.0.0.1:7004/v1/client/onboard" -H  "accept: text/plain" -H  "Content-Type: application/json" -d "{\"bearerToken\":\"eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2MzEwODYxODUsImlhdCI6MTYzMTA4NTI4NSwiaXNzIjoiZGlkOmVic2k6NGpQeGNpZ3ZmaWZaeVZ3eW01emp4YUtYR0pUdDdZd0Z0cGc2QVh0c1I0ZDUiLCJvbmJvYXJkaW5nIjoicmVjYXB0Y2hhIiwidmFsaWRhdGVkSW5mbyI6eyJhY3Rpb24iOiJsb2dpbiIsImNoYWxsZW5nZV90cyI6IjIwMjEtMDktMDhUMDc6MTQ6NDRaIiwiaG9zdG5hbWUiOiJhcHAucHJlcHJvZC5lYnNpLmV1Iiwic2NvcmUiOjAuOSwic3VjY2VzcyI6dHJ1ZX19.InIzqVIAON07zuFkt6afLv3q6IO9XuqcmiH8CnVo6lMfFQMBv1Uz91-gkn__0RuYzzTgzPWBCmUn8E3tw_xE5Q\",\"did\":\"did:ebsi:22tCpv2yh4EJLm6o18JiS2AebaQAL6QcHH83mS6Cz94QumtY\"}"

EBSI/ESSIF Auth flow

curl -X POST "http://127.0.0.1:7004/v1/client/auth" -H  "accept: text/plain" -H  "Content-Type: text/plain" -d "did:ebsi:22tCpv2yh4EJLm6o18JiS2AebaQAL6QcHH83mS6Cz94QumtY"

EBSI/ESSIF DID registration

curl -X POST "http://127.0.0.1:7004/v1/client/registerDid" -H  "accept: text/plain" -H  "Content-Type: text/plain" -d "did:ebsi:22tCpv2yh4EJLm6o18JiS2AebaQAL6QcHH83mS6Cz94QumtY"

DID Resolution (only to check if the DID was correctly anchored with the EBSI blockchain)

curl -X POST "http://127.0.0.1:7000/v1/did/resolve" -H  "accept: text/plain" -H  "Content-Type: application/json" -d "{\"did\":\"did:ebsi:22tCpv2yh4EJLm6o18JiS2AebaQAL6QcHH83mS6Cz94QumtY\"}"

Code example

The did:ebsi example shows how to register an EBSI DID in Java.

    KeyService keyService = KeyService.Companion.getService();
    DidEbsiService didEbsiService = DidEbsiService.Companion.getService();

    var keyId = keyService.generate(KeyAlgorithm.ECDSA_Secp256k1);
 
    var didEbsi = DidService.INSTANCE.create(DidMethod.ebsi, keyId.getId());

    EssifClient.INSTANCE.onboard(didEbsi, null);

    EssifClient.INSTANCE.authApi(didEbsi);

    didEbsiService.registerDid(didEbsi, ethKeyId.getId());

Build end-to-end use cases

This is a holistic SSI use case, which demonstrates the setup of two identities for an Issuer and a Holder on the EBSI blockchain. It also shows the steps to issue two diploma credentials to the Holder (e.g student), which then creates a Verifiable Presentation including both credentials in order to be verified. The Verifier then resolves the DIDs from the EBSI ledger and uses the corresponding public keys to verify the signatures from the issued credentials.

CLI

Creating a work-dir for all three parties of the trust triangle (Issuer, Holder & Verifier)

mkdir issuer
mkdir holder
mkdir verifier

Setting up the Issuer (generating a key, EBSI DID and registering it on the EBSI ledger)

cd issuer/
docker run -itv $(pwd)/data:/app/data waltid/ssikit key gen -a Secp256k1
docker run -itv $(pwd)/data:/app/data waltid/ssikit did create -m ebsi -k 48ff0d51910c4dc4b05b420547a05f9f
cat > data/bearer-token.txt    
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif onboard --did did:ebsi:22NPNHrBUWCKDJWuvpJD5s2V7JZNQRQvajMHP9hiky57nfhC data/bearer-token.txt
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif auth-api --did did:ebsi:22NPNHrBUWCKDJWuvpJD5s2V7JZNQRQvajMHP9hiky57nfhC
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif did register --did did:ebsi:22NPNHrBUWCKDJWuvpJD5s2V7JZNQRQvajMHP9hiky57nfhC

Setting up the Holder (generating a key, EBSI DID and registering it on the EBSI ledger)

cd ../holder/
docker run -itv $(pwd)/data:/app/data waltid/ssikit key gen -a Secp256k1
docker run -itv $(pwd)/data:/app/data waltid/ssikit did create -m ebsi -k 2c497f88593b4db9a571fb7146606fc2
cat > data/bearer-token.txt   
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif onboard --did did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr data/bearer-token.txt
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif auth-api --did did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr
docker run -itv $(pwd)/data:/app/data waltid/ssikit essif did register --did did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr

Setting up the Verifier (only run ssikit in order to initialize the work-dir)

cd ../verifier/
docker run -itv $(pwd)/data:/app/data waltid/ssikit -h

Issuing two credentials, one Bachelor & one Master degree (values are defined by running the interactive shell). Both credentials are based on the VerifiableDiploma Template

cd ../issuer/
docker run -itv $(pwd)/data:/app/data waltid/ssikit vc issue -i did:ebsi:22NPNHrBUWCKDJWuvpJD5s2V7JZNQRQvajMHP9hiky57nfhC -s did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr -t VerifiableDiploma --interactive data/bachelor.json
docker run -itv $(pwd)/data:/app/data waltid/ssikit vc issue -i did:ebsi:22NPNHrBUWCKDJWuvpJD5s2V7JZNQRQvajMHP9hiky57nfhC -s did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr -t VerifiableDiploma --interactive data/master.json
cp data/master.json data/bachelor.json ../holder/data

Creating the Verifiable Presentation containing both - the Master and the Bachelor credential

cd ../holder/
docker run -itv $(pwd)/data:/app/data waltid/ssikit vc present --holder-did did:ebsi:2YiP8ae91JPNQ86YQWvPytdBP8rfKZYR8r95CE8aZ1ooUatr data/master.json data/bachelor.json
cp data/vc/presented/vp-1632686198721.json ../verifier/data

Verifying the Verifiable Presentation by resolving DIDs (public keys) from the EBSI ledger and verifying the signatures from each VC (Bachelor & Master degree credential) and from the VP itself.

docker run -itv $(pwd)/data:/app/data waltid/ssikit vc verify -p TrustedIssuerDidPolicy -p TrustedSubjectDidPolicy -p JsonSchemaPolicy -p SignaturePolicy data/vp-1632686198721.json

Output:    
Walt.ID SSI-Kit 1.0-SNAPSHOT (running on Java 16.0.2+7-67)

Verifying from file data/vp-1632686198721.json ...

Results:

TrustedIssuerDidPolicy:          true
TrustedSubjectDidPolicy:                 true
JsonSchemaPolicy:                true
Verified:                true

Note that the order of the policies does matter. The TrustedIssuerDidPolicy & TrustedSubjectDidPolicy are verifying the presents of the DIDs on the EBSI ledger, and if they are, the keys are imported to the key-store. Once the keys are available, the SignaturePolicy can be applied in order to verify each signature.

IOTA

We apologize that our current implementation does not yet support the Stardust Upgrade from IOTA. As such, you cannot issue or verify credentials associated via a did:iota. Please refer to our roadmap for more information on when our products will be updated to include this latest changes.

The following section outlines the planned integration of the IOTA identity framework with the walt.id SSI Kit and gives insight on the architecture of the integration and the required changes that need to be applied to the SSI Kit to establish smooth interoperability with the IOTA ecosystem.

Introduction

The IOTA identity framework, much like the walt.id SSI Kit, is based on open standards for decentralized identity, such as the W3C specifications for verifiable credentials and decentralized identifiers (DIDs) and provides creation, management and registration of DIDs on the IOTA DLT technology (tangle), as well, as issuance, signing and validation of verifiable credentials.

In addition to the open standards for decentralized identity, the IOTA identity frameword implements a custom DID method, which needs to be supported by the walt.id SSI Kit to ensure compatibility.

Integration overview

Thanks to the use of W3C standards for DID documents and verifiable credentials, the SSI Kit is mostly compatible with the IOTA identity framework, with regards to DID documents and issuance/validation of verifiable credentials. Also the key type Ed25519, used in the IOTA framework is already supported by the SSI Kit.

The following aspects have been identified, which require implementation changes and/or integration work in the SSI Kit:

IOTA DID method: Creation, management and registration of DIDs on the IOTA tangle
Key management: Integrate SSI Kit key management seamlessly, such that keys managed by the SSI Kit (or a supported key store implementation) can be leveraged in the context of the IOTA framework.
Signature type: To ensure compatibility of issued credentials with both the SSI Kit and the IOTA framework, the LD-signature type JcsEd25519Signature2020 needs to be supported in the SSI Kit.
Public key format: The public key, stored in the verification methods of the IOTA DID documents, is formatted in multibase encoding, for which support in the SSI Kit needs to be provided.

The following subsections give more details on the planned integration work.

Integration architecture

The following chart outlines the overall architecture of the integration between the walt.id SSI Kit and the IOTA framework:

Rust library wrapper

In order to overcome the native-to-managed-code gap between the IOTA identity framework libraries, written in Rust, and the SSI Kit in Kotlin/JVM, a wrapper library is implemented in Rust, which includes the IOTA libraries as a dependency and exposes a plain C-compatible application binary interface (ABI).

The wrapper library can be loaded in Kotlin/JVM using the JNR-FFI abstracted foreign function layer library. The advantage compared to JNI (Java Native Interface) is that no Java-specific interface code needs to be written in the native wrapper library, such that the same library could be used from various other programming and scripting languages, that support loading of native dynamic libraries.

This approach also facilitates portability of the wrapper library to all operating systems and platforms supported by the Rust compiler and the IOTA framework library.

DID management

For DID creation and management, the wrapper library implements an interface method, called by the IotaService component in the SSI Kit.

The public and private keys for creating the DID, should be managed by the SSI Kit and its key store abstraction layer, with support for various key store implementations (see also Key management below).

The wrapper library makes use of the AccountBuilder of the identity_iota::account module to create and register a DID on the IOTA ledger. After creation the library updates the DID document to include the various verification method relationships, such that issuance (assertionMethod) and presentation (authentication) of verifiable credentials is permitted using the new DID.

The created DID document is returned to the SSI Kit, where it can be parsed and stored for further use.

Key management

In order to be able to make full use of the SSI Kit together with the IOTA framework, it is preferred to share the key store between both worlds.

The SSI Kit provides a key store abstraction layer, that has support for various key store implementations, including an embedded key store and cryptography library, as well as cloud-based HSM stores, such as Azure key vault and the walt.id Storage Kit, a general-purpose distributed encrypted data store.

In order to leverage the SSI Kit key store abstraction with the IOTA identity framework integration, we plan to implement a key store mediator component in the Rust wrapper library, which exposes the IOTA storage interface on the one hand, and, on the other hand, communicates the signing or encryption/decryption requests to the SSI Kit via a native-to-managed callback function. This key store mediator can be passed to the AccountBuilder as to storage interface to use for DID creation. The SSI Kit can then fulfill the cryptographic requests using the configured key store implementation and hand back the result to the wrapper library and IOTA framework internals.

LD signature type

The IOTA identity framework makes use of the JcsEd25519Signature2020 LD-signature type for signing and validation of verifiable credentials.

Thus, to be compatible with the credentials issued by the IOTA framework,the SSI Kit needs to be extended to support this type of signature.

DID documents and verification material

To make the SSI Kit compatible with the DID documents created by the IOTA identity framework, it is required to support Multibase encoding of the verification material in the verification method objects, according to the latest DID specification, as for the time being, an older version of said specification is implemented, using Base58 encoding.

Given the support of multibase encoded verification material, the DID documents should be fully compatible with the SSI Kit.

Velocity

Intro to Velocity Network

Velocity Network Foundation

Velocity NetworkTM is a public permissioned distributed network, based on a permissioned version of the Ethereum Blockchain utilizing Hyperledger Besu. Operating a node and writing to the Velocity Ledger requires permission from the Velocity Network FoundationR.

The following data is stored on chain:

organization metadata - DID, profile, endpoint
credential metadata (encrypted) - ID, type, public key, revocation status
verification voucher transactions
credential types and schemas

Network participants

High level

Holder - a person that holds the credential on behalf of the subject (themselves or another person)
Issuer - an organization that creates and issues credentials
- first party issuer - an entity that can directly attest to the claims within the credential
- notary issuer - an entity that can evaluate evidence to attest to the claims within the credential
Relying Party - an entity that requests and verifies credentials from a Holder

Low level

Wallet Provider (Holder App Provider) - an organization offering digital wallets to be used by Holders
Credential Agent Operator - an organization operating a credential agent
- Agent - an interface to the network used by organizations (Issuer, Relying Party, Holder) - call contracts, retrieve account states - form the 'layer-2' network
  - Tenant - an organization’s delegate on which behalf the agent is acting
Node Operator - an organization operating a node
- Node - a participant on the network holding copies of the underlying ledger
  - Members (Stewards) - read-only nodes with limited data access that forward write operations to Validators
  - Validators - full-write permission nodes that participate in consensus
Velocity Network Registrar - a set of centralized services that are used for administering the accredited organizations and credential types on the Network
Credits hub - a module where Velocity credits are administered and credit reward transactions can be executed
Voucher hub - a module where Velocity vouchers are administered and top up transactions can be executed
The ledger - the distributed blockchain-based, continuously-replicated, global cryptographic database maintained by Stewards operating nodes communicating with the Velocity consensus protocol

Workflows

Issuing - the process of asserting claims about a Holder who receives the verifiable credential
- by writing a transaction to the Velocity Ledger which includes the credential ID, its type, the Issuer ID, and the public key matching the private key that signed it
Revocation - the act of an Issuer revoking the validity of a credential
- by writing a transaction to the Velocity Ledger marking the credential as revoked
Verification - the process of confirming that a verifiable credential is not modified, revoked or expired and is issued by a trusted authority
- by accessing the Velocity Ledger to retrieve the unique public key associated with credential and verify its signature

Verifiable Credentials

Velocity currently uses the JWT format for encoding credentials with JWS signatures using SECP256K1 as proofs.

Verifiable credentials are divided into the following categories:

Layer-1 credential types - network’s core set of credential types (e.g. Email, IdDocument, OpenBadgeCredential)
- for each issued credential, the Issuer receives a reward in the form of Velocity Credits
Layer-2 credential types - any custom credential type
- should be mapped to a Layer-1 type in order for the Issuer to be eligible for a reward

More about credential types here https://docs.velocitynetwork.foundation/docs/developers/basics-credential-types.

Decentralized identifiers

did:ion - used to identify organizations or individuals
- received when registering with the Registrar
did:velocity - used to identify credentials
- is immutable
- stores only a single key and credential type
- resolving it will burn an NFT to permit DID resolution

Basics

This section describes the main steps required to interact with Velocity network:

onboarding (did registration)
issuing credentials
inspecting credentials

Issuing

Issuing involves an exchange between a Holder and an Issuer, by which the Holder receives a set of offers from the Issuer. Once the Holder accepts the offers, the Issuer converts them into verifiable credentials and supplies them to the Holder.

Depending on data source location and process initiating party, the following issuing types are supported:

custom - credential agent loads offers from itself as well as calling out webhooks
- demand triggered - Holder initiates the credential claiming process
  - Issuer responds with the available credential offers according to Holder’s criteria
- supply triggered - Issuer initiates the credential claiming process
  - offers are made available to the Holder using a notification mechanism by sending a deep-link or qr-code to claim the credentials
batch - credential agent loads offers only from itself
- a specialized version of supply triggered custom issuing

More information on issuing can be found at https://docs.velocitynetwork.foundation/docs/developers/developers-guide-issuing.

Inspection

The verification process (inspection) is initiated by disclosure exchanges where the Relying Party requests credentials from Holder. These exchanges can be encoded in the following ways:

deep links - a URI that matches the spec:
QR-codes - a visual representation of a deep link

Depending on the use case, the Relying Party can request either:

verified credentials
- requires payment in tokens
- returns the verification checks (policies) result
unverified credentials:
- requires no payment in tokens
- can be verified later

Verification policies

The verification checks performed against the credential are the following:

UNTAMPERED
- pass - hasn't been tampered
- fail - has been tampered
- voucher_reserve_exhausted - a voucher is required for verification
TRUSTED_ISSUER
- pass - issuer is trusted
- fail - issuer is not a member of Velocity
- self_signed - data attested by the Holder
- voucher_reserve_exhausted - a voucher is required for verification
UNREVOKED
- pass - hasn't been revoked
- has been revoked
- voucher_reserve_exhausted - a voucher is required for verification
UNEXPIRED
- pass - hasn't expired
- fail - has expired

More details on credential verification checks can be found at https://docs.velocitynetwork.foundation/docs/developers/developers-guide-disclosure-exchange#credential-verification-checks.

More on credential verification at https://docs.velocitynetwork.foundation/docs/developers/developers-guide-disclosure-exchange.

Integration with SSIKit

The interaction with Velocity network is implemented in SSIKit using a Rest API client which currently exposes the functionality through the command-line-interface. The available functions can grouped as follows:

organization related
- onboarding
- tenant configuration
credential related
- issuance
- verification

In order to cover the credential related functions, but also tenant management, SSIKit uses a credential agent deployed on walt.id infrastructure. For this, walt.id is registered on Velocity network (currently only on testnet) as a credential agent operator and can issue and verify credentials on behalf of issuer using either issuer's keys or walt.id keys. The diagram below shows how Velocity integration is currently done with SSIKit.

The organization related functions, such as onboarding and DID acquisition, are implemented by calling Velocity network registrar Rest API.