KMS Service - Key Management Service

A unified Key Management Service for the Provisioning platform with support for multiple backends.

Source: provisioning/platform/kms-service/

Supported Backends

• Age: Fast, offline encryption (development)
• RustyVault: Self-hosted Vault-compatible API
• Cosmian KMS: Enterprise-grade with confidential computing
• AWS KMS: Cloud-native key management
• HashiCorp Vault: Enterprise secrets management

Architecture

┌─────────────────────────────────────────────────────────┐
│                    KMS Service                          │
├─────────────────────────────────────────────────────────┤
│  REST API (Axum)                                        │
│  ├─ /api/v1/kms/encrypt       POST                      │
│  ├─ /api/v1/kms/decrypt       POST                      │
│  ├─ /api/v1/kms/generate-key  POST                      │
│  ├─ /api/v1/kms/status        GET                       │
│  └─ /api/v1/kms/health        GET                       │
├─────────────────────────────────────────────────────────┤
│  Unified KMS Service Interface                          │
├─────────────────────────────────────────────────────────┤
│  Backend Implementations                                │
│  ├─ Age Client (local files)                           │
│  ├─ RustyVault Client (self-hosted)                    │
│  └─ Cosmian KMS Client (enterprise)                    │
└─────────────────────────────────────────────────────────┘

Quick Start

Development Setup (Age)

# 1. Generate Age keys
mkdir -p ~/.config/provisioning/age
age-keygen -o ~/.config/provisioning/age/private_key.txt
age-keygen -y ~/.config/provisioning/age/private_key.txt > ~/.config/provisioning/age/public_key.txt

# 2. Set environment
export PROVISIONING_ENV=dev

# 3. Start KMS service
cd provisioning/platform/kms-service
cargo run --bin kms-service

Production Setup (Cosmian)

# Set environment variables
export PROVISIONING_ENV=prod
export COSMIAN_KMS_URL=https://your-kms.example.com
export COSMIAN_API_KEY=your-api-key-here

# Start KMS service
cargo run --bin kms-service

REST API Examples

Encrypt Data

curl -X POST http://localhost:8082/api/v1/kms/encrypt \
  -H "Content-Type: application/json" \
  -d '{
    "plaintext": "SGVsbG8sIFdvcmxkIQ==",
    "context": "env=prod,service=api"
  }'

Decrypt Data

curl -X POST http://localhost:8082/api/v1/kms/decrypt \
  -H "Content-Type: application/json" \
  -d '{
    "ciphertext": "...",
    "context": "env=prod,service=api"
  }'

Nushell CLI Integration

# Encrypt data
"secret-data" | kms encrypt
"api-key" | kms encrypt --context "env=prod,service=api"

# Decrypt data
$ciphertext | kms decrypt

# Generate data key (Cosmian only)
kms generate-key

# Check service status
kms status
kms health

# Encrypt/decrypt files
kms encrypt-file config.yaml
kms decrypt-file config.yaml.enc

Backend Comparison

Integration Points

1. Config Encryption (SOPS Integration)
2. Dynamic Secrets (Provider API Keys)
3. SSH Key Management
4. Orchestrator (Workflow Data)
5. Control Center (Audit Logs)

Deployment

Docker

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && \
    apt-get install -y ca-certificates && \
    rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/kms-service /usr/local/bin/
ENTRYPOINT ["kms-service"]

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kms-service
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: kms-service
        image: provisioning/kms-service:latest
        env:
        - name: PROVISIONING_ENV
          value: "prod"
        - name: COSMIAN_KMS_URL
          value: "https://kms.example.com"
        ports:
        - containerPort: 8082

Security Best Practices

1. Development: Use Age for dev/test only, never for production secrets
2. Production: Always use Cosmian KMS with TLS verification enabled
3. API Keys: Never hardcode, use environment variables
4. Key Rotation: Enable automatic rotation (90 days recommended)
5. Context Encryption: Always use encryption context (AAD)
6. Network Access: Restrict KMS service access with firewall rules
7. Monitoring: Enable health checks and monitor operation metrics

Related Documentation

• User Guide: KMS Guide
• Migration: KMS Simplification