Enclave - Secure Key Management Service

A secure key management service built with Rust, featuring a dual-mode architecture that supports both local development and production deployment with AWS Nitro Enclaves.

Overview

Enclave is a cryptographic key management solution that provides secure key generation, digital signatures, and verification operations. It supports two deployment modes:

Local Mode: For development and testing with local storage
Enclave Mode: For production with AWS Nitro Enclaves and KMS encryption

Features

🔐 Multi-Algorithm Support: Ed25519 and Secp256k1 cryptographic algorithms
🏗️ Dual Architecture: Local development and production Enclave modes
🛡️ Hardware Security: AWS Nitro Enclaves for production deployment
🔑 KMS Integration: AWS KMS for encryption/decryption in Enclave mode
🌐 JSON-RPC API: HTTP API following JSON-RPC 2.0 standard
📦 Docker Support: Containerized deployment with Docker Compose
🔧 Flexible Storage: Multiple storage backends (File, Database)
🚀 High Performance: Async/await architecture with Tokio

Architecture

Local Development Mode

┌────────────────────────────────────────────────────┐
│                    Local Service                   │
│  ┌──────────────────────────────────────────────┐  │
│  │  HTTP JSON-RPC Server (Port 8080)            │  │
│  │  ┌─────────────────┐    ┌─────────────────┐  │  │
│  │  │  Key Manager    │    │  Storage        │  │  │
│  │  │  - Generate     │    │  - File System  │  │  │
│  │  │  - Sign/Verify  │    │  - Database     │  │  │
│  │  └─────────────────┘    └─────────────────┘  │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘

Production Enclave Mode

┌───────────────────────────────────────────────────────┐
│           Client Service (Parent Instance)            │
│  ┌─────────────────────────────────────────────────┐  │
│  │  HTTP JSON-RPC Server (Port 8080)               │  │
│  │  ┌─────────────────┐    ┌────────────────────┐  │  │
│  │  │  Request Router │    │  Response Handler  │  │  │
│  │  └─────────────────┘    └────────────────────┘  │  │
│  │  ┌───────────────────────────────────────────┐  │  │
│  │  │  Vsock Client (Port 5005)                 │  │  │
│  │  └───────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌───────────────────────────────────────────────────────┐
│                AWS Nitro Enclave                      │
│  ┌─────────────────────────────────────────────────┐  │
│  │  Vsock Server (Port 5005)                       │  │
│  │  ┌─────────────────┐    ┌─────────────────┐     │  │
│  │  │  KMS Integration│    │  Key Manager    │     │  │
│  │  │  - kmstool genkey│   │  - Generate     │     │  │
│  │  │  - kmstool decrypt│  │  - Sign/Verify  │     │  │
│  │  │  - AWS KMS      │    │  - AES Encrypt  │     │  │
│  │  └─────────────────┘    └─────────────────┘     │  │
│  │  ┌───────────────────────────────────────────┐  │  │
│  │  │  Secure Key Storage (Hardware Isolated)   │  │  │
│  │  │  - Encrypted Private Keys                 │  │  │
│  │  │  - KMS Ciphertext Blobs                   │  │  │
│  │  └───────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘

Key Generation Workflow

Inside Enclave
├─ 1. Receive key generation request
├─ 2. kmstool genkey (generate AES data key)
│   ├─ Call AWS KMS GenerateDataKey
│   ├─ Get (ciphertext, plaintext)
│   └─ plaintext is AES key
├─ 3. Generate original key pair
├─ 4. Encrypt private key with AES key
├─ 5. Store encrypted private key + KMS ciphertext
└─ 6. Return KeyPair (with encrypted private key)

Signing Workflow

Inside Enclave
├─ 1. Receive signing request
├─ 2. kmstool decrypt (decrypt KMS ciphertext)
│   ├─ Call AWS KMS Decrypt
│   └─ Get AES key
├─ 3. Decrypt private key with AES key
├─ 4. Sign with original private key
└─ 5. Return signature

Quick Start

Prerequisites

Rust 1.90+
Docker (optional)
AWS CLI (for Enclave mode)

Installation

# Clone the repository
git clone https://github.com/iamnivekx/enclave.git
cd enclave

# Build the project
cargo build --release

Local Development

# Start local server
cargo run --bin enclave-node -- server --port 5005

# Start local client
cargo run --bin enclave-node -- client --port 5005 --http-port 8080

Production Deployment

Prerequisites for Enclave Mode

Before starting the enclave application, you need to set up the vsock-proxy for KMS communication:

Option 1: Using systemd services (Recommended)

# Start the nitro-enclaves-allocator service
sudo systemctl start nitro-enclaves-allocator.service

# Enable and start the vsock-proxy service
sudo systemctl enable --now nitro-enclaves-vsock-proxy.service

Option 2: Manual vsock-proxy setup

# Start vsock-proxy manually (replace with your AWS region)
vsock-proxy 8000 kms.ap-east-1.amazonaws.com 443 &

The vsock-proxy forwards requests from port 8000 on the parent instance to the KMS endpoint (kms.ap-east-1.amazonaws.com:443). Make sure to use the correct AWS region for your deployment.

Starting the Services

# Start Enclave server
cargo run --bin enclave-node -- server --region us-east-1 --key-id your-kms-key-id --port 5005

# Start Client service
cargo run --bin enclave-node -- client --cid 16 --port 5005 --http-port 8080

Docker Deployment

build the kmstool-enclave-cli image as base image

git clone https://github.com/aws/aws-nitro-enclaves-sdk-c.git
cd aws-nitro-enclaves-sdk-c
./bin/kmstool-enclave-cli
./build.sh

docker image ls

# Build images
docker build -t enclave-client -f Dockerfile.client .
docker build -t enclave-server -f Dockerfile.server .

# Run with Docker Compose
docker-compose up -d

API Usage

JSON-RPC Interface

The service provides a JSON-RPC 2.0 compatible API:

Generate Key Pair

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "generate_key",
    "params": {"algo": "Ed25519"},
    "id": 1
  }'

Sign Message

# Note: message needs to be Base64 encoded
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "sign",
    "params": {
      "algo": "ed25519",
      "privkey": "dGVzdC1wcml2YXRlLWtleS1kYXRh", // Base64 encoded private key
      "message": "SGVsbG8gV29ybGQ=" // Base64 encoded "Hello World"
    },
    "id": 2
  }'

Response Example:

{
  "jsonrpc": "2.0",
  "result": {
    "algo": "ed25519",
    "pubkey": "dGVzdC1wdWJsaWMta2V5LWRhdGE=",
    "signature": "dGVzdC1zaWduYXR1cmUtZGF0YQ=="
  },
  "id": 2
}

Verify Signature

# Verify signature using public key
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "verify",
    "params": {
      "algo": "ed25519",
      "pubkey": "dGVzdC1wdWJsaWMta2V5LWRhdGE=", // Base64 encoded public key
      "message": "SGVsbG8gV29ybGQ=", // Base64 encoded "Hello World"
      "signature": "dGVzdC1zaWduYXR1cmUtZGF0YQ==" // Base64 encoded signature
    },
    "id": 3
  }'

Response Example:

{
  "jsonrpc": "2.0",
  "result": true,
  "id": 3
}

Health Check

curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "system.health",
    "params": [],
    "id": 4
  }'

Configuration

Environment Variables

Variable	Description	Default	Required
`ENCLAVE_CID`	Enclave CID for vsock communication	1	No
`ENCLAVE_HOST`	Enclave host address	127.0.0.1	No
`ENCLAVE_PORT`	Enclave port	5005	Yes
`SERVICE_PORT`	HTTP service port	8080	No
`SERVICE_KEY_STORE_PATH`	Key storage path	./keys	No
`ENCLAVE_REGION`	AWS region for KMS	-	Yes (Enclave mode)
`ENCLAVE_KEY_ID`	KMS key ID	-	Yes (Enclave mode)

Storage Backends

File Storage (Default)

[storage]
backend = "file"
path = "./keys"

Database Storage

[storage]
backend = "database"
url = "postgresql://user:password@localhost/enclave"
table_name = "key_pairs"

Project Structure

enclave/
├── Cargo.toml                 # Workspace configuration
├── Dockerfile.client          # Client Docker image
├── Dockerfile.server          # Server Docker image
├── docker-compose.yml         # Docker Compose configuration
├── crates/
│   ├── enclave-node/          # Main service binary
│   │   ├── src/
│   │   │   ├── main.rs        # Entry point
│   │   │   ├── commands/      # CLI commands
│   │   │   ├── nitro/         # Enclave communication
│   │   │   ├── server.rs      # RPC server
│   │   │   └── storage.rs     # Storage wrapper
│   │   └── Cargo.toml
│   ├── enclave-types/         # Core types and traits
│   │   ├── src/
│   │   │   ├── key.rs         # Key types and traits
│   │   │   ├── health.rs      # Health types
│   │   │   ├── algo.rs        # Algorithm enum
│   │   │   └── error.rs       # Error types
│   │   └── Cargo.toml
│   ├── enclave-storage/       # Storage abstraction
│   │   ├── src/
│   │   │   ├── backends/      # Storage implementations
│   │   │   ├── config.rs      # Storage configuration
│   │   │   └── manager.rs     # Storage manager
│   │   └── Cargo.toml
│   ├── enclave-keyring/       # Cryptographic keyring
│   │   ├── src/
│   │   │   ├── keyring/       # Algorithm implementations
│   │   │   └── registry.rs    # Keyring registry
│   │   └── Cargo.toml
│   └── rpc/                   # RPC components
│       ├── rpc-api/           # RPC API definitions
│       ├── rpc/               # RPC implementations
│       └── rpc-client/        # RPC client
└── keys/                      # Local key storage

Development

Building

# Build all crates
cargo build

# Build specific crate
cargo build -p enclave-node

# Build with features
cargo build --features kms

Testing

# Run all tests
cargo test

# Run specific tests
cargo test -p enclave-types

# Run with logging
RUST_LOG=debug cargo test

Linting

# Run clippy
cargo clippy

# Run clippy with all targets
cargo clippy --all-targets --all-features

Security

Enclave

Private keys encrypted by AWS KMS-generated AES keys
Hardware-level security isolation
All key operations performed inside Enclave
Private keys never leave the Enclave in plaintext
Double encryption: KMS encrypts data keys + AES encrypts private keys
Supports attestation verification

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Run cargo test and cargo clippy
Submit a pull request

nivek3/enclave

README