provisioning/docs/src/security/kms-service.md

# 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

| Feature | Age | RustyVault | Cosmian KMS | AWS KMS | Vault |
| --------- | ----- | ------------ | ------------- | --------- | ------- |
| **Setup** | Simple | Self-hosted | Server setup | AWS account | Enterprise |
| **Speed** | Very fast | Fast | Fast | Fast | Fast |
| **Network** | No | Yes | Yes | Yes | Yes |
| **Key Rotation** | Manual | Automatic | Automatic | Automatic | Automatic |
| **Data Keys** | No | Yes | Yes | Yes | Yes |
| **Audit Logging** | No | Yes | Full | Full | Full |
| **Confidential** | No | No | Yes (SGX/SEV) | No | No |
| **License** | MIT | Apache 2.0 | Proprietary | Proprietary | BSL/Enterprise |
| **Cost** | Free | Free | Paid | Paid | Paid |
| **Use Case** | Dev/Test | Self-hosted | Privacy | AWS Cloud | Enterprise |

## 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](../user/RUSTYVAULT_KMS_GUIDE.md)
- **Migration**: [KMS Simplification](../migration/KMS_SIMPLIFICATION.md)