README.md

ssi-service

A web service that exposes the ssi-sdk as an HTTP API. Support operations for Verifiable Credentials, Decentralized Identifiers and things Self Sovereign Identity!

Introduction

The Self Sovereign Identity Service (SSIS) facilitates all things relating to DIDs and Verifiable Credentials - in a box! The service is a part of a larger Decentralized Web Platform architecture which you can learn more about in our collaboration repo.

Core Functionality

• Create and manage Decentralized Identifiers
• Create and manage Verifiable Credentials
• Credential Suspension
• Interacting with the standards around Verifiable Credentials such as
  • Credential Revocations
  • Applying for Credentials
  • Exchanging Credentials
  • Data Schemas (for credentials and other verifiable data)

Use Cases (more to come!)

Business: Issuing Verifiable Credentials

Follow Tutorial

Steps to issue an Employment Status Credential:

1. Spin up and host the SSI-Service
2. Add the ability for your employees to click 'apply for a credential' on your internal EMS (should we show a front end button code example)
3. Create an Issuer DID for your business
4. Create a Schema
5. Create a Credential Manifest
6. Submit a Credential Application

Configuration

Managed via: TOML file

There are sets of configuration values for the server (e.g. which port to listen on), the services (e.g. which database to use), and each service. Each service may define specific configuration, such as which DID methods are enabled for the DID service.

Key Management

SSI-service can store keys that are used to digitally sign credentials (and other data). All such keys are encrypted at the application before being stored using a MasterKey (a.k.a. a Key Encryption Key or KEK). The MasterKey can be generated automatically during boot time based on a password, or we can use the MasterKey housed in an external Key Management System (KMS) like GCP KMS or AWS KMS.

For production deployments, using external KMS is strongly recommended.

To use an external KMS:

1. Create a symmetric encryption key in your KMS. You MUST select the algorithm that uses AES-256 block cipher in Galois/Counter Mode (GCM). At the time of writing, this is the only algorithm supported by AWS and GCP.
2. Set the master_key_uri field of the [services.keystore] section using the format described in tink (we use the tink library under the hood).
3. Set the kms_credentials_path field of the [services.keystore] section to point to your credentials file, according to this section.
4. Win!

To use a password based MasterKey (NOT RECOMMENDED FOR ANY PRODUCTION ENVIRONMENT):

1. Make sure that master_key_uri and kms_credentials_path of the [services.keystore] section are not set.
2. Set the password field of the [services.keystore] section to your desired password.

Note that at this time, we do not currently support rotating the master key.

Steps for SSI-Service to consume its configuration:

1. On startup: SSI-Service loads default values into the SSIServiceConfig
2. Checks for a TOML config file:

• If exists...load toml file
• If does not exist...it uses a default config defined in the code inline

3. Finally, it loads the config/.env file and adds the env variables defined in this file to the final SSIServiceConfig

Pre-built images to use

There are pre-build images built by github actions on each merge to the main branch, which you can access here: https://github.com/orgs/TBD54566975/packages?repo_name=ssi-service

Build & Test

This project uses mage, please view CONTRIBUTING for more information.

After installing mage, you can build and test the SDK with the following commands:

mage build
mage test

A utility is provided to run clean, build, lint, and test in sequence with:

mage cblt

Deployment

The service is packaged as a Docker container, runnable in a wide variety of environments.

Docker Compose is used for simplification and orchestration. To run the service, you can use the following command, which will start the service on port 8080:

mage run

Or, you can run docker-compose yourself, building from source:

cd build && docker-compose up --build

To use the pre-published images:

cd build && docker-compose up -d

Health and Readiness Checks

Note: port 3000 is used by default, specified in config.toml, for the SSI Service process. If you're running via mage run or docker compose, the port to access will be 8080.

Run for health check (status: OK, then you are up):

 ~ curl localhost:3000/health
{"status":"OK"}

Run to check if all services are up and ready (credential, did, and schema):

~ curl localhost:8080/readiness
{
    "status": {
        "status": "ready",
        "message": "all service ready"
    },
    "serviceStatuses": {
        "credential": {
            "status": "ready"
        },
        "did": {
            "status": "ready"
        },
        "schema": {
            "status": "ready"
        }
    }
}

Continuous Integration

CI is managed via GitHub Actions. Actions are triggered to run for each Pull Request, and on merge to main. You can run CI locally using a tool like act.

HTTP Endpoints

You can find all HTTP endpoints by checking out the swagger docs at: http://localhost:8080/swagger

Note: Your port may differ; swagger docs are hosted on the same endpoint as the ssi service itself.

What's Supported?

• DID Management
  • did:key
  • did:web
  • did:ion Note: updates not yet supported
  • did:pkh Resolution only
  • did:peer Resolution only
• Verifiable Credential Schema Management
• Verifiable Credential Issuance & Verification
  • Signing and verification with JWTs
  • Signing and verification with Data Integrity Proofs
• Applying for Verifiable Credentials using Credential Manifest
• Requesting, Receiving, and the Validation of Verifiable Claims using Presentation Exchange
• Status of Verifiable Credentials using the Status List 2021
• DID Well Known Configuration documents
• Creating and managing Trust documents using Trust Establishment

Vision, Features, and Development

The vision for the project is laid out in this document.

The project follows a proposal-based improvement format called SIPs, outlined here..

Please join Discord, or open an issue if you are interested in helping shape the future of the project.

Project Resources

Resource	Description
Components Readme	Documentation for various components of the SSI Service
VISION	Outlines the project vision
SIPs	Proposals for improving the SSI Service
VERSIONING	Project versioning strategy
CODEOWNERS	Outlines the project lead(s)
CODE_OF_CONDUCT	Expected behavior for project contributors, promoting a welcoming environment
CONTRIBUTING	Developer guide to build, test, run, access CI, chat, discuss, file issues
GOVERNANCE	Project governance
SECURITY	Vulnerability and bug reporting
LICENSE	Apache License, Version 2.0