KMS Exercise

Overview

This repository contains a coding exercise for implementing a private KMS import/export service.

High-level goal

Implement a private KMS import/export service that lets a client:

1. Start an import session → receive an ImportEnvelope and session public key.
2. Finish the import → TEE decrypts material, stores it encrypted under the TEE master key, returns a wallet_id.
3. Export that wallet encrypted for any caller-supplied P-256 public key.

Mandatory crypto rules

• Everything (key-gen, AES-GCM, ECIES, signing, random) runs inside a secure-environment service.
• Wallet data at rest is encrypted with a single TEE-resident key.
• Bonus points: Add an optional proof so clients can verify the TEE really generated the session key.

You can assume that authentication has already been handled by another system. There's also no need to link any user private keys - just treat the database as if it's personal to the user making the call.

Architecture Overview

This project implements the KMS service with a clear trust boundary separation:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────────┐
│   Client App    │    │    KMS API       │    │ Secure Environment  │
│   (port 3002)   │◄──►│  (untrusted)     │◄──►│    (trusted)        │
│                 │    │   port 3002      │    │    port 3000        │
└─────────────────┘    └──────────────────┘    └─────────────────────┘

Security Model

• KMS API: Considered untrusted - acts as a coordinator
• Secure Environment: Trusted - handles all cryptographic operations
• All encryption/decryption operations must occur within the secure environment

Components

1. Secure Environment Service (src/projects/secure-environment/)

Trusted Component - Handles all cryptographic operations

• Port: 3000
• Responsibilities:
  • Key generation and management using RootKey
  • Symmetric encryption/decryption (AES-GCM)
  • Public key exposure for client verification
  • Secure cryptographic operations isolation
  • All SecureRuntime.trustedEnvExec calls happen here

2. KMS API Service (src/projects/kms-api/)

Untrusted Component - API Coordinator

• Port: 3002
• Responsibilities:
  • Client-facing API endpoints
  • Coordination of requests to secure environment
  • No direct cryptographic operations
  • Service health monitoring
  • Cannot perform any cryptographic operations directly

3. Client Example (src/projects/client-example/)

Demonstration Client

• Demonstrates complete import/export workflow
• Interacts with KMS API (not directly with secure environment)

Getting Started

Prerequisites

• Rust 1.85.0 or later
• Cargo package manager

Running the Services

1. Start the Secure Environment (must run first):

cargo run --bin secure-environment

2. Start the KMS API (in a new terminal):

cargo run --bin kms-api

3. Run the Client Example (in a new terminal):

cargo run --bin client-example

Implementation Requirements

Your implementation should include:

1. Import Session Initiation: Generate session keys and return import envelope
2. Import Completion: Decrypt imported material and store securely
3. Export Functionality: Export wallets encrypted for caller's public key
4. Secure Execution: All cryptographic operations must run within SecureRuntime.trustedEnvExec
5. TEE Master Key: Single key for encrypting wallet data at rest
6. Trust Boundary: KMS API must never perform crypto operations - only coordinate with secure environment

Security Features

1. Trust Boundary Enforcement

• All cryptographic operations isolated to secure environment
• KMS API cannot perform encryption/decryption operations
• Clear separation between trusted and untrusted components

2. Cryptographic Security

• AES-256-GCM: Authenticated symmetric encryption
• P-256 ECDSA: Digital signatures for authenticity
• ECIES: Hybrid encryption for asymmetric operations
• HKDF: Secure key derivation with domain separation

Bonus Features

• Optional proof generation to verify TEE-generated session keys

Testing

Run the full test suite:

cargo test