Shamir Secret Sharing API Documentation

API Overview

The Shamir Secret Sharing API provides both cryptographic functions and distributed storage capabilities through RESTful endpoints and gRPC services.

Version: 1.0.0

Authentication

All endpoints except / and /register require JWT authentication.

POST
/register

Register a new user account.

Request Body

{
  "username": "string",
  "password": "string"
}

Response

{
  "msg": "User registered successfully"
}
POST
/login

Authenticate and receive JWT token.

Request Body

{
  "username": "string",
  "password": "string"
}

Response

{
  "access_token": "string",
  "token_type": "bearer"
}

Core API Endpoints

GET
/protected

Test authenticated route.

Headers

Authorization: Bearer {token}

Response

{
  "msg": "Hello, {username}. This is a protected route."
}
POST
/store-key

Store a secret key-value pair using Shamir's algorithm.

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request Body

KeyValueSecret

{
  key: string;    // Unique identifier for the secret
  value: string;  // The secret value to store
}

Response

HTTP 201 Created on success

POST
/get-key

Retrieve a previously stored secret.

Headers

Authorization: Bearer {token}
Content-Type: application/json

Request Body

KeySecret

{
  key: string;  // The identifier of the secret to retrieve
}

Response

{
  "secret": "string"  // The reconstructed secret value
}

gRPC API Documentation

Master Service

Central coordination service for managing slave nodes and secret distribution.

Connect - Handshake for slave registration 
rpc Connect(ConnectionRequest) returns (ConnectionResponse);
  
  message ConnectionRequest {}  // Empty request
  
  message ConnectionResponse {
    bool approve = 1;  // Connection approval status
  }

Python Implementation

class MasterServer(cf_grpc.MasterServicer):
      def Connect(self, request, context):
          peer = context.peer()  # Get client IP
          # Register slave in database
          slave_manager.add(peer.split(':')[1])
          return cf.ConnectionResponse(approve=True)

Slave Service

Service for storing and retrieving secret parts on slave nodes.

PutSecretPart - Store a secret part 
rpc PutSecretPart(SecretPart) returns (Key);
  
  message SecretPart {
    Key key = 1;    // Secret identifier
    bytes part = 2; // Encrypted secret part
  }
GetSecretPart - Retrieve a secret part 
rpc GetSecretPart(Key) returns (SecretPart);
  
  message Key {
    uint64 key = 1;  // Secret identifier
  }

Connection Flow

def start_slave(master_host, port):
      # Connect to master first
      if connect_to_master(master_host):
          # Start gRPC server
          server = grpc.server(futures.ThreadPoolExecutor())
          cf_grpc.add_SlaveServicer_to_server(SlaveServer(), server)
          server.add_insecure_port(f"0.0.0.0:{port}")
          server.start()

Proto Compilation

Compile .proto files using the provided script:

./compile_proto.sh
  # Generates:
  # - resources/generated/*_pb2.py
  # - resources/generated/*_pb2_grpc.py
  # - resources/generated/*_pb2.pyi (mypy types)

Error Codes

Code Description
400 Bad request (invalid parameters)
401 Unauthorized (invalid/missing token)
404 Secret not found
500 Internal server error