init

2025-02-18 16:21:47 +08:00
commit 4af69eb3dd
7 changed files with 2599 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,419 @@
+# DSKE POC (Client)
+
+## 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](https://gitea.devchristam.com/devchristam/dske_poc_client)
+- [server](https://gitea.devchristam.com/devchristam/dske_poc_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:
+
+```bash
+# 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:
+
+```sh
+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:
+
+```sh
+# 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:
+
+```sh
+# 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`):
+```json
+{
+    "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:
+
+```json
+{
+    "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`):
+
+```json
+{
+    "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`):
+```json
+{
+    "client_id": 2,
+    "client_url": "http://localhost:8002",
+    "keysize": 5
+}
+```
+
+![screenshot](./Screenshot.png)
+
+## API Documentation
+
+### Server
+
+#### `POST /register_client`
+
+Registers a client in the security hub.
+
+- **Input:**
+
+  `content-type: "application/json"`
+
+  ```json
+  {
+      "id": Integer,
+      "username": String,
+      "url": String
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "id": 999,
+      "username": "test",
+      "url": "http://localhost:8888"
+  }
+  ```
+
+- **Output:**
+
+  ```json
+  {
+      "id": Integer,
+      "username": String,
+      "url": String,
+      "random_bits": Boolean[]
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "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:**
+
+  ```json
+  Integer[]
+  ```
+
+  Example:
+
+  ```json
+  [1, 2, 3, ...]
+  ```
+
+#### `POST /generate_key_instruction`
+
+Generates a key instruction for the key exchange process.
+
+- **Input:**
+
+  `content-type: "application/json"`
+
+  ```json
+  {
+      "sender_id": Integer,
+      "receiver_id": Integer,
+      "hash": Integer,
+      "keysize": Integer
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "sender_id": 1,
+      "receiver_id": 2,
+      "hash": 12345,
+      "keysize": 5
+  }
+  ```
+
+- **Output:**
+
+  ```json
+  Boolean[]
+  ```
+
+  Example:
+
+  ```json
+  [true, false, true, ...]
+  ```
+
+### Client
+
+#### `POST /register_securityhub`
+
+Registers a security hub in the client.
+
+- **Input:**
+
+  `content-type: "application/json"`
+
+  ```json
+  {
+      "securityhub_id": Integer,
+      "securityhub_url": String,
+      "random_bits": Boolean[]
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "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"`
+
+  ```json
+  {
+      "client_id": Integer,
+      "client_url": String,
+      "keysize": Integer
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "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"`
+
+  ```json
+  {
+      "client_id": Integer,
+      "securityhub_list": Integer[],
+      "keysize": Integer
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "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"`
+
+  ```json
+  {
+      "sender_id": Integer,
+      "hash": Integer,
+      "key_instruction": Boolean[],
+      "total": Integer,
+      "securityhub_id": Integer
+  }
+  ```
+
+  Example:
+
+  ```json
+  {
+      "sender_id": 1,
+      "hash": 1234,
+      "key_instruction": [true, false, ...],
+      "total": 2,
+      "securityhub_id": 1
+  }
+  ```
+
+- **Output:**
+
+  Null