# KMS Service - Key Management Service\n\nA unified Key Management Service for the Provisioning platform with support for multiple backends.\n\n> **Source**: `provisioning/platform/kms-service/`\n\n## Supported Backends\n\n- **Age**: Fast, offline encryption (development)\n- **RustyVault**: Self-hosted Vault-compatible API\n- **Cosmian KMS**: Enterprise-grade with confidential computing\n- **AWS KMS**: Cloud-native key management\n- **HashiCorp Vault**: Enterprise secrets management\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    KMS Service                          │\n├─────────────────────────────────────────────────────────┤\n│  REST API (Axum)                                        │\n│  ├─ /api/v1/kms/encrypt       POST                      │\n│  ├─ /api/v1/kms/decrypt       POST                      │\n│  ├─ /api/v1/kms/generate-key  POST                      │\n│  ├─ /api/v1/kms/status        GET                       │\n│  └─ /api/v1/kms/health        GET                       │\n├─────────────────────────────────────────────────────────┤\n│  Unified KMS Service Interface                          │\n├─────────────────────────────────────────────────────────┤\n│  Backend Implementations                                │\n│  ├─ Age Client (local files)                           │\n│  ├─ RustyVault Client (self-hosted)                    │\n│  └─ Cosmian KMS Client (enterprise)                    │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Quick Start\n\n### Development Setup (Age)\n\n```\n# 1. Generate Age keys\nmkdir -p ~/.config/provisioning/age\nage-keygen -o ~/.config/provisioning/age/private_key.txt\nage-keygen -y ~/.config/provisioning/age/private_key.txt > ~/.config/provisioning/age/public_key.txt\n\n# 2. Set environment\nexport PROVISIONING_ENV=dev\n\n# 3. Start KMS service\ncd provisioning/platform/kms-service\ncargo run --bin kms-service\n```\n\n### Production Setup (Cosmian)\n\n```\n# Set environment variables\nexport PROVISIONING_ENV=prod\nexport COSMIAN_KMS_URL=https://your-kms.example.com\nexport COSMIAN_API_KEY=your-api-key-here\n\n# Start KMS service\ncargo run --bin kms-service\n```\n\n## REST API Examples\n\n### Encrypt Data\n\n```\ncurl -X POST http://localhost:8082/api/v1/kms/encrypt \\n  -H "Content-Type: application/json" \\n  -d '{\n    "plaintext": "SGVsbG8sIFdvcmxkIQ==",\n    "context": "env=prod,service=api"\n  }'\n```\n\n### Decrypt Data\n\n```\ncurl -X POST http://localhost:8082/api/v1/kms/decrypt \\n  -H "Content-Type: application/json" \\n  -d '{\n    "ciphertext": "...",\n    "context": "env=prod,service=api"\n  }'\n```\n\n## Nushell CLI Integration\n\n```\n# Encrypt data\n"secret-data" | kms encrypt\n"api-key" | kms encrypt --context "env=prod,service=api"\n\n# Decrypt data\n$ciphertext | kms decrypt\n\n# Generate data key (Cosmian only)\nkms generate-key\n\n# Check service status\nkms status\nkms health\n\n# Encrypt/decrypt files\nkms encrypt-file config.yaml\nkms decrypt-file config.yaml.enc\n```\n\n## Backend Comparison\n\n| Feature | Age | RustyVault | Cosmian KMS | AWS KMS | Vault |\n| --------- | ----- | ------------ | ------------- | --------- | ------- |\n| **Setup** | Simple | Self-hosted | Server setup | AWS account | Enterprise |\n| **Speed** | Very fast | Fast | Fast | Fast | Fast |\n| **Network** | No | Yes | Yes | Yes | Yes |\n| **Key Rotation** | Manual | Automatic | Automatic | Automatic | Automatic |\n| **Data Keys** | No | Yes | Yes | Yes | Yes |\n| **Audit Logging** | No | Yes | Full | Full | Full |\n| **Confidential** | No | No | Yes (SGX/SEV) | No | No |\n| **License** | MIT | Apache 2.0 | Proprietary | Proprietary | BSL/Enterprise |\n| **Cost** | Free | Free | Paid | Paid | Paid |\n| **Use Case** | Dev/Test | Self-hosted | Privacy | AWS Cloud | Enterprise |\n\n## Integration Points\n\n1. **Config Encryption** (SOPS Integration)\n2. **Dynamic Secrets** (Provider API Keys)\n3. **SSH Key Management**\n4. **Orchestrator** (Workflow Data)\n5. **Control Center** (Audit Logs)\n\n## Deployment\n\n### Docker\n\n```\nFROM rust:1.70 as builder\nWORKDIR /app\nCOPY . .\nRUN cargo build --release\n\nFROM debian:bookworm-slim\nRUN apt-get update && \\n    apt-get install -y ca-certificates && \\n    rm -rf /var/lib/apt/lists/*\nCOPY --from=builder /app/target/release/kms-service /usr/local/bin/\nENTRYPOINT ["kms-service"]\n```\n\n### Kubernetes\n\n```\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: kms-service\nspec:\n  replicas: 2\n  template:\n    spec:\n      containers:\n      - name: kms-service\n        image: provisioning/kms-service:latest\n        env:\n        - name: PROVISIONING_ENV\n          value: "prod"\n        - name: COSMIAN_KMS_URL\n          value: "https://kms.example.com"\n        ports:\n        - containerPort: 8082\n```\n\n## Security Best Practices\n\n1. **Development**: Use Age for dev/test only, never for production secrets\n2. **Production**: Always use Cosmian KMS with TLS verification enabled\n3. **API Keys**: Never hardcode, use environment variables\n4. **Key Rotation**: Enable automatic rotation (90 days recommended)\n5. **Context Encryption**: Always use encryption context (AAD)\n6. **Network Access**: Restrict KMS service access with firewall rules\n7. **Monitoring**: Enable health checks and monitor operation metrics\n\n## Related Documentation\n\n- **User Guide**: [KMS Guide](../user/RUSTYVAULT_KMS_GUIDE.md)\n- **Migration**: [KMS Simplification](../migration/KMS_SIMPLIFICATION.md)