DSKE POC (Security Hub Server)

Introduction

This is a proof of concept for the DSKE system. The main goal is to demonstrate the algorithm in DSKE. There are a few assumptions and limitations in this proof-of-concept project:

1. This is not a working protocol, this project is just to prove the algorithm concept.
2. This project is demonstrating a simple DSKE protocol, which means n = k. It is a (n, n) secret sharing scheme.
3. The code assumes that the final key sender chooses all common security hubs with the receiver that they both register.

This project is separated into two parts: the client and the security hub server.

• client
• server

You need to host multiple clients and servers to make this proof-of-concept DSKE system work.

DSKE Main Phases

1. PSKM Generation and Distribution

   The security hub's POST /register_client endpoint will generate random bits and record the client on the server side. This endpoint will return the generated random bits. The client's POST /register_securityhub endpoint will store these random bits so that both the security hub and the client have a copy. Note that the distribution process needs to be done manually because real PSKM distribution is done physically.

2. Peer Identity Establishment

   When a client wants to share a key with another client using POST /make_connection, the sender client will send a request to the receiver client's POST /agree_connection endpoint with a list of security hubs to use in the key exchange. The receiver client will check if both the sender and receiver are registered in those security hubs using the security hub's POST /user_list endpoint. This endpoint will display every client ID registered in the security hub, allowing the client to identify common security hubs.

3. Key Agreement

   The sender will use the POST /make_connection endpoint to exchange keys with the receiver.

   1. Share Generation

      The proof-of-concept project will use an (n, n) secret sharing scheme in a simple DSKE protocol. For simplicity, the sender will choose all the common security hubs with the receiver.

   2. Share Distribution

      The sender will send a request to the security hub's POST /generate_key_instruction endpoint to generate a key instruction A (sender's random bits) XOR B (receiver's random bits).

   3. Key Reconstruction

      After the security hub sends a request to the client's POST /receive_key_instruction endpoint, the client will calculate A ^ B ^ B to retrieve A in each request and store the calculated A in a key-value pair using the final key hash as the key. The receiver can reconstruct the final key S by executing XOR on every share in the simple DSKE protocol (n, n) secret sharing scheme.

4. Key Validation

   The receiver will only reconstruct the final key if the number of received shares equals the total number of shares. The exchange process will abort if the numbers do not match.

Step-by-Step Setup Guide

This guide will walk you through the steps to set up and run the DSKE POC server and client.

Steps

1. Clone the Repository

Clone the repository to your local machine using the following commands:

# Clone the DSKE POC server
git clone https://gitea.devchristam.com/devchristam/dske_poc_server.git

# Clone the DSKE POC client
git clone https://gitea.devchristam.com/devchristam/dske_poc_client.git

2. Build the Project

Navigate to the project directory and build the project using Cargo:

cargo build

3. Run the Server and Client

Run the server and client using the following commands. You need to use Tmux or open multiple terminal applications to host multiple servers and clients on the same machine.

For server:

# The code supports .env for port and security hub ID settings.
# Even if not using the .env file, please copy the .env because missing variables will show a runtime error.
cp .env.sample .env
# set the environment variables in .env if needed
# cargo run -- <port> <security hub id>
# e.g.
cargo run -- 8081 1
cargo run -- 8082 2
cargo run -- 8083 3

For client:

# The code supports .env for port and security hub ID settings.
# Even if not using the .env file, please copy the .env because missing variables will show a runtime error.
cp .env.sample .env
# set the environment variables in .env if needed
# cargo run -- <port> <user id>
# e.g.
cargo run -- 8001 1
cargo run -- 8002 2

4. Exchange Key

Steps

All API calls use content-type: "application/json".

1. Register Client in Security Hub

Use the security hub endpoint POST /register_client to record the client.

• Example (record a client running on cargo run -- 8001 1):

{
    "id": 1,
    "username": "alice",
    "url": "http://localhost:8001"
}

• This request will return a payload. You need to copy the random_bits array for step 2:

{
    "id": 1,
    "username": "alice",
    "url": "http://localhost:8001",
    "random_bits": [
        false,
        false,
        true,
        true,
        true,
        ...
    ]
}

2. Register Security Hub in the Client

Copy the random_bits array and input the same content into the client endpoint POST /register_securityhub.

• Example (record a security hub running on cargo run -- 8081 1):

{
    "securityhub_id": 1,
    "securityhub_url": "http://localhost:8081",
    "random_bits": [
        false,
        false,
        true,
        true,
        true,
        ...
    ]
}

After repeating steps 1 and 2, you can create a proof-of-concept DSKE system network. Then the client can exchange keys within the network.

3. Exchange Key

In the client endpoint POST /make_connection, you can exchange the final key with another client.

• Example (from client cargo run -- 8001 1 exchanging key with cargo run -- 8002 2):

{
    "client_id": 2,
    "client_url": "http://localhost:8002",
    "keysize": 5
}

API Documentation

Server

POST /register_client

Registers a client in the security hub.

• Input:

  content-type: "application/json"

  {
      "id": Integer,
      "username": String,
      "url": String
  }
  

  Example:

  {
      "id": 999,
      "username": "test",
      "url": "http://localhost:8888"
  }
  

• Output:

  {
      "id": Integer,
      "username": String,
      "url": String,
      "random_bits": Boolean[]
  }
  

  Example:

  {
      "id": 999,
      "username": "test",
      "url": "http://localhost:8888",
      "random_bits": [true, false, true, ...]
  }
  

POST /user_list

Retrieves the list of registered user IDs from the security hub.

• Input:

  No input required.

• Output:

  Integer[]
  

  Example:

  [1, 2, 3, ...]
  

POST /generate_key_instruction

Generates a key instruction for the key exchange process.

• Input:

  content-type: "application/json"

  {
      "sender_id": Integer,
      "receiver_id": Integer,
      "hash": Integer,
      "keysize": Integer
  }
  

  Example:

  {
      "sender_id": 1,
      "receiver_id": 2,
      "hash": 12345,
      "keysize": 5
  }
  

• Output:

  Boolean[]
  

  Example:

  [true, false, true, ...]
  

Client

POST /register_securityhub

Registers a security hub in the client.

• Input:

  content-type: "application/json"

  {
      "securityhub_id": Integer,
      "securityhub_url": String,
      "random_bits": Boolean[]
  }
  

  Example:

  {
      "securityhub_id": 1,
      "securityhub_url": "http://localhost:8081",
      "random_bits": [true, false, true, ...]
  }
  

• Output:

  Null

POST /make_connection

Initiates a key exchange with another client.

• Input:

  content-type: "application/json"

  {
      "client_id": Integer,
      "client_url": String,
      "keysize": Integer
  }
  

  Example:

  {
      "client_id": 2,
      "client_url": "http://localhost:8002",
      "keysize": 5
  }
  

• Output:

  Null

POST /agree_connection

Agrees to a key exchange initiated by another client. Check the securityhub_list are both registered or not.

• Input:

  content-type: "application/json"

  {
      "client_id": Integer,
      "securityhub_list": Integer[],
      "keysize": Integer
  }
  

  Example:

  {
      "client_id": 1,
      "securityhub_list": [1, 2],
      "keysize": 5
  }
  

• Output:

  Null

If the exchange cannot process, the API will not return 200 OK.

POST /receive_key_instruction

Receives a key instruction from the security hub.

• Input:

  content-type: "application/json"

  {
      "sender_id": Integer,
      "hash": Integer,
      "key_instruction": Boolean[],
      "total": Integer,
      "securityhub_id": Integer
  }
  

  Example:

  {
      "sender_id": 1,
      "hash": 1234,
      "key_instruction": [true, false, ...],
      "total": 2,
      "securityhub_id": 1
  }
  

• Output:

  Null