Decentralised Key Management SystemDecentralised Key Management System
DKMS Concepts
Developer Guide
DKMS Concepts
Developer Guide
  • Developer Guide

    • Infrastructure
    • Clients

Infrastructure

DKMS infrastructure is composed of two main components: Witnesses and Watchers. Both are available as Docker images:

  • Witness
  • Watcher

For sample setup, see this. and for more information see setup section.

Argo

Argo is a sandbox which allows you to test right away the DKMS infrastructure without need to setup anything. Checkout our public dashboard to see the current state of the network.

Setup

If you would like to run your own DKMS network, follow the instructions below or simply try dkms-demo which is ready to be run locally with docker compose.

Deploy witnesses

Witnesses play a crucial role in the DKMS infrastructure. They are responsible for disseminating information across the network. In addition witnesses produce reciepts for the controllers as a form of confirmation that he has seen the latest KEL.

Witness is available as a Docker image. Which can be eailsy deploy, below example using docker compose:

services:
  witness: &witness
    container_name: keriox-witness
    image: "ghcr.io/thclab/keriox-witness:latest"
    restart: always
    networks:
      - dkms-network


  witness1:
    container_name: keriox-witness1
    <<: *witness
    ports:
      - "3232:3232"
    volumes:
      - type: bind
        source: ./config/witness1.yml
        target: /app/witness.yml
      - witness1_db_data:/app/db

Warning

Never use latest tag for docker image for production systems. Always use specific version. See Release page

Configuration

To run witness you need to provide a configuration file. Below is an example of it with explanation of each field:

db_path: "db/" # path to the database where witness would store KEL's
http_port: 3232 # port on which witness will listen for incoming connections
public_url: "http://172.17.0.1:3232/" # public URL of the witness
seed: "<YOUR_SEED_GOES_HERE" # seed of the witness to generate private key, keep this secret!
escrow_config: # Configuration for the escrow system, which acts as a buffer for processing events from KELs
  default_timeout: 60 # Time (in seconds) before an event is discarded after the last processing attempt. Event is processed only when new event comes.

Generate seed

The seed is necessary to generate the private key for the witness. By definition witness operate with empheral keys means they cannot be rotated. If the key is compromised, the witness should be replaced with a new one. To generate the seed you can use dkms-cli tool:

The seed should be set in the configuration file. Keep it secret!

Run witness

Simply run docker contaienrs with docker-compose up -d command.

After the witness is running you can check the logs with docker logs keriox-witness command. And you should see something like this:

keriox-witness1  | Witness BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC is listening on port 3232
keriox-witness1  | Witness's oobi: {"eid":"BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC","scheme":"http","url":"http://localhost:3232/"}

Deploy watchers

Watchers are responsible for detecting duplicity in the network. They are also available as a Docker image. Below is an example of how to deploy them:

watcher:
  container_name: keriox-watcher
  image: "ghcr.io/thclab/keriox-watcher:latest"
  restart: always
  depends_on:
    - witness
  ports:
    - "3235:3235"
  volumes:
    - type: bind
      source: ./config/watcher.yml
      target: /app/watcher.yml
    - watcher_db_data:/app/db/
  networks:
    - dkms-network

Configuration

To run watcher you need to provide a configuration file. Below is an example of it with explanation of each field:

db_path: "db/" # path to the database where watcher would store KEL's
tel_storage_path: "db/tel_storage" # path to the database where watcher would store TEL's
public_url: "http://172.17.0.1:3235" # public url of the watcher
seed: "<HERE_GOES_SEEF_OF_THE_WATCHER" # seed of the watcher to generate private key, keep this secret!
http_port: 3235 # port on which watcher will listen for incoming connections
escrow_config: # Configuration for the escrow system, which acts as a buffer for processing events from KELs
  default_timeout: 60 # Time (in seconds) before an event is discarded after the last processing attempt. Event is processed only when new event comes.

Generate seed

To generate seed see the Generate seed section in the witness configuration.

Run watcher

Simply run docker contaienrs with docker-compose up -d command.

After the watcher is running you can check the logs with docker logs keriox-watcher command. And you should see something like this:

keriox-watcher  | Using config file: "./watcher.yml"
keriox-watcher  | Using environment prefix: "WATCHER_"
keriox-watcher  | Watcher BF2t2NPc1bwptY1hYV0YCib1JjQ11k9jtuaZemecPF5b is listening on port 3236
keriox-watcher  | Watcher's oobi: {"eid":"BF2t2NPc1bwptY1hYV0YCib1JjQ11k9jtuaZemecPF5b","scheme":"http","url":"http://localhost:3236/"}

Next Steps

After you have deployed witnesses and watchers, you can start using the DKMS-CLI to start interacting with them. See the CLI documentation for more information.

Last Updated:: 3/28/25, 1:54 PM
Contributors: blelump, Robert Mitwicki
Next
Clients