Enclave

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

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

License

This project is licensed under the MIT OR Apache-2.0 dual license.

Support

Issues: GitHub Issues
Documentation: Project Wiki

References

$$

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github		.github
crates		crates
docs		docs
examples		examples
.clippy.toml		.clippy.toml
.gitignore		.gitignore
.rustfmt.toml		.rustfmt.toml
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
Dockerfile.client		Dockerfile.client
Dockerfile.dev		Dockerfile.dev
Dockerfile.server		Dockerfile.server
README.md		README.md
RUST_GUIDELINES.md		RUST_GUIDELINES.md
agents.md		agents.md
docker-compose.yml		docker-compose.yml
env.example		env.example
rust-toolchain.toml		rust-toolchain.toml

Latest commit

History

Folders and files

Repository files navigation

Enclave - Secure Key Management Service