{$detected_lang}\n┌─────────────────────────────────────────────────\n────────┐\n│ KMS Service │\n├─────────────────────────────────────────────────\n────────┤\n│ REST API (Axum) │\n│ ├─ /api/v1/kms/encrypt POST │\n│ ├─ /api/v1/kms/decrypt POST │\n│ ├─ /api/v1/kms/generate-key POST (Cosmian only) │\n│ ├─ /api/v1/kms/status GET │\n│ └─ /api/v1/kms/health GET │\n├─────────────────────────────────────────────────\n────────┤\n│ Unified KMS Service Interface │\n│ ├─ encrypt(plaintext, context) -> ciphertext │\n│ ├─ decrypt(ciphertext, context) -> plaintext │\n│ ├─ generate_data_key(spec) -> DataKey │\n│ └─ health_check() -> bool │\n├─────────────────────────────────────────────────\n────────┤\n│ Backend Implementations │\n│ ├─ Age Client │\n│ │ ├─ X25519 encryption │\n│ │ ├─ Local key files │\n│ │ └─ Offline operation │\n│ └─ Cosmian KMS Client │\n│ ├─ REST API integration │\n│ ├─ Zero-knowledge encryption │\n│ └─ Confidential computing │\n└─────────────────────────────────────────────────\n────────┘\n\n\n## Installation\n\n### Prerequisites\n\n- Rust 1.70+ (for building)\n- Age 1.2+ (for development backend)\n- Cosmian KMS server (for production backend)\n- Nushell 0.107+ (for CLI integration)\n\n### Build from Source\n\n{$detected_lang}\ncd provisioning/platform/kms-service\ncargo build --release\n\n# Binary will be at: target/release/kms-service\n\n\n## Configuration\n\n### Configuration File\n\nCreate provisioning/config/kms.toml:\n\n{$detected_lang}\n[kms]\ndev_backend = "age"\nprod_backend = "cosmian"\nenvironment = "${PROVISIONING_ENV:-dev}"\n\n[kms.age]\npublic_key_path = "~/.config/provisioning/age/public_key.txt"\nprivate_key_path = "~/.config/provisioning/age/private_key.txt"\n\n[kms.cosmian]\nserver_url = "${COSMIAN_KMS_URL:-https://kms.example.com}"\napi_key = "${COSMIAN_API_KEY}"\ndefault_key_id = "provisioning-master-key"\ntls_verify = true\n\n\n### Environment Variables\n\n{$detected_lang}\n# Development with Age\nexport PROVISIONING_ENV=dev\n# Age keys will be read from paths in config\n\n# Production with Cosmian\nexport PROVISIONING_ENV=prod\nexport COSMIAN_KMS_URL="https://kms.example.com"\nexport COSMIAN_API_KEY="your-api-key"\n\n\n## Quick Start\n\n### Development Setup (Age)\n\n{$detected_lang}\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\ncargo run --bin kms-service\n\n\n### Production Setup (Cosmian)\n\n{$detected_lang}\n# 1. Set up Cosmian KMS server (or use hosted service)\n\n# 2. Create master key in Cosmian KMS\n# (Use Cosmian KMS CLI or web interface)\n\n# 3. 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# 4. Start KMS service\ncargo run --bin kms-service\n\n\n## Usage\n\n### REST API Examples\n\n#### Encrypt Data\n\n{$detected_lang}\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{$detected_lang}\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#### Generate Data Key (Cosmian only)\n\n{$detected_lang}\ncurl -X POST http://localhost:8082/api/v1/kms/generate-key \\n -H "Content-Type: application/json" \\n -d '{\n "key_spec": "AES_256"\n }'\n\n\n#### Health Check\n\n{$detected_lang}\ncurl http://localhost:8082/api/v1/kms/health\n\n\n### Nushell CLI Integration\n\n{$detected_lang}\n# Load the KMS module\nuse provisioning/core/nulib/kms\n\n# Set service URL\nexport KMS_SERVICE_URL="http://localhost:8082"\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$ciphertext | kms decrypt --context "env=prod,service=api"\n\n# Generate data key (Cosmian only)\nkms generate-key\nkms generate-key --key-spec AES_128\n\n# Check service status\nkms status\nkms health\n\n# Encrypt/decrypt files\nkms encrypt-file config.yaml\nkms encrypt-file secrets.json --output secrets.enc --context "env=prod"\n\nkms decrypt-file config.yaml.enc\nkms decrypt-file secrets.enc --output secrets.json --context "env=prod"\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| Multi-tenant | No | Yes | Yes | Yes | Yes |\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\n### 1. Config Encryption (SOPS Integration)\n\n{$detected_lang}\n# Encrypt configuration files\nkms encrypt-file workspace/config/secrets.yaml\n\n# SOPS can use KMS for key encryption\n# Configure in .sops.yaml to use KMS endpoint\n\n\n### 2. Dynamic Secrets (Provider API Keys)\n\n{$detected_lang}\n// Rust orchestrator can call KMS API\nlet encrypted_key = kms_client.encrypt(api_key.as_bytes(), &context).await?;\n\n\n### 3. SSH Key Management\n\n{$detected_lang}\n# Generate and encrypt temporal SSH keys\nssh-keygen -t ed25519 -f temp_key -N ""\nkms encrypt-file temp_key --context "infra=prod,purpose=deployment"\n\n\n### 4. Orchestrator (Workflow Data)\n\n{$detected_lang}\n// Encrypt sensitive workflow parameters\nlet encrypted_params = kms_service\n .encrypt(params_json.as_bytes(), &workflow_context)\n .await?;\n\n\n### 5. Control Center (Audit Logs)\n\n- All KMS operations are logged\n- Audit trail for compliance\n- Integration with control center UI\n\n## Testing\n\n### Unit Tests\n\n{$detected_lang}\ncargo test\n\n\n### Integration Tests\n\n{$detected_lang}\n# Age backend tests (no external dependencies)\ncargo test age\n\n# Cosmian backend tests (requires Cosmian KMS server)\nexport COSMIAN_KMS_URL=http://localhost:9999\nexport COSMIAN_API_KEY=test-key\ncargo test cosmian -- --ignored\n\n\n## Deployment\n\n### Docker\n\n{$detected_lang}\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 (Production with Cosmian)\n\n{$detected_lang}\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 - name: COSMIAN_API_KEY\n valueFrom:\n secretKeyRef:\n name: cosmian-api-key\n key: api-key\n ports:\n - containerPort: 8082\n\n\n### systemd Service\n\n{$detected_lang}\n[Unit]\nDescription=KMS Service\nAfter=network.target\n\n[Service]\nType=simple\nUser=kms-service\nEnvironment="PROVISIONING_ENV=prod"\nEnvironment="COSMIAN_KMS_URL=https://kms.example.com"\nEnvironment="COSMIAN_API_KEY=your-api-key"\nExecStart=/usr/local/bin/kms-service\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\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 Cosmian API keys, use environment variables\n4. Key Rotation: Enable automatic rotation in Cosmian (90 days recommended)\n5. Context Encryption: Always use encryption context (AAD) for additional security\n6. Network Access: Restrict KMS service access with firewall rules\n7. Monitoring: Enable health checks and monitor operation metrics\n\n## Migration from Vault/AWS KMS\n\nSee KMS_SIMPLIFICATION.md for migration guide.\n\n## Monitoring\n\n### Metrics Endpoints\n\n{$detected_lang}\n# Service status (includes operation count)\ncurl http://localhost:8082/api/v1/kms/status\n\n# Health check\ncurl http://localhost:8082/api/v1/kms/health\n\n\n### Logs\n\n{$detected_lang}\n# Set log level\nexport RUST_LOG="kms_service=debug,tower_http=debug"\n\n# View logs\njournalctl -u kms-service -f\n\n\n## Troubleshooting\n\n### Age Backend Issues\n\n{$detected_lang}\n# Check keys exist\nls -la ~/.config/provisioning/age/\n\n# Verify key format\ncat ~/.config/provisioning/age/public_key.txt\n# Should start with: age1...\n\n# Test encryption manually\necho "test" | age -r $(cat ~/.config/provisioning/age/public_key.txt) > test.enc\nage -d -i ~/.config/provisioning/age/private_key.txt test.enc\n\n\n### Cosmian KMS Issues\n\n{$detected_lang}\n# Check connectivity\ncurl https://kms.example.com/api/v1/health \\n -H "X-API-Key: $COSMIAN_API_KEY"\n\n# Verify API key\ncurl https://kms.example.com/api/v1/version \\n -H "X-API-Key: $COSMIAN_API_KEY"\n\n# Test encryption\ncurl -X POST https://kms.example.com/api/v1/encrypt \\n -H "X-API-Key: $COSMIAN_API_KEY" \\n -H "Content-Type: application/json" \\n -d '{"keyId":"master-key","data":"SGVsbG8="}'\n\n\n## License\n\nCopyright © 2024 Provisioning Team\n\n## References\n\n- Age Encryption\n- Cosmian KMS\n- Axum Web Framework\n- Confidential Computing