6.1 KiB
6.1 KiB
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\n- Migration: KMS Simplification