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.

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.

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.

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.

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

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:

• OpenID Connect for Credential Issuance (OpenID4CI)

• OpenID for Verifiable Presentations (OpenID4VP)

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.

The architecture of the SSI Kit consists of three layers:

1. Low-Level Services Abstraction: Abstracts complex, low-level operations (e.g. cryptography, key management, digital signatures, data storage).

2. Ecosystem Abstraction: Abstracts ecosystem-specific requirements based on the relevant technical and governance frameworks (e.g. SSI flavors, business logic, policies).

3. 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.

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.

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.

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.

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.

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).

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:

• Introduction to Digital Identity

• Introduction to Self-Sovereign Identity

• Introduction to NFTs for Identity

• Case studies from our users.

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.

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.

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.

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:

1. 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.

2. Validate that the DID of the holder, stated in the certificate, is the person presenting the VC.

3. Checking if all the state values are valid (expiration date and if the certificate is revoked or not).

4. 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.

5. 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="
  }
}

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.

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:

1. Presentation Layer - Being the Verifiable Presentation itself with the required metadata

2. Credential Layer - Referenced by Layer 1 and pointing to one or more credentials

3. Credential Proof Layer - Holding the proofs of the credentials and the signatures from Layer

4. 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"
      ]
    }
  ]
}

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"
    }]
}