# ADR-007: KMS Service Simplification to Age and Cosmian Backends\n\n**Status**: Accepted\n**Date**: 2025-10-08\n**Deciders**: Architecture Team\n**Related**: ADR-006 (KMS Service Integration)\n\n## Context\n\nThe KMS service initially supported 4 backends: HashiCorp Vault, AWS KMS, Age, and Cosmian KMS. This created unnecessary complexity and unclear\nguidance about which backend to use for different environments.\n\n### Problems with 4-Backend Approach\n\n1. **Complexity**: Supporting 4 different backends increased maintenance burden\n2. **Dependencies**: AWS SDK added significant compile time (~30 s) and binary size\n3. **Confusion**: No clear guidance on which backend to use when\n4. **Cloud Lock-in**: AWS KMS dependency limited infrastructure flexibility\n5. **Operational Overhead**: Vault requires server setup even for simple dev environments\n6. **Code Duplication**: Similar logic implemented 4 different ways\n\n### Key Insights\n\n- Most development work doesn't need server-based KMS\n- Production deployments need enterprise-grade security features\n- Age provides fast, offline encryption perfect for development\n- Cosmian KMS offers confidential computing and zero-knowledge architecture\n- Supporting Vault AND Cosmian is redundant (both are server-based KMS)\n- AWS KMS locks us into AWS infrastructure\n\n## Decision\n\nSimplify the KMS service to support only 2 backends:\n\n1. **Age**: For development and local testing\n   - Fast, offline, no server required\n   - Simple key generation with `age-keygen`\n   - X25519 encryption (modern, secure)\n   - Perfect for dev/test environments\n\n2. **Cosmian KMS**: For production deployments\n   - Enterprise-grade key management\n   - Confidential computing support (SGX/SEV)\n   - Zero-knowledge architecture\n   - Server-side key rotation\n   - Audit logging and compliance\n   - Multi-tenant support\n\nRemove support for:\n\n- ❌ HashiCorp Vault (redundant with Cosmian)\n- ❌ AWS KMS (cloud lock-in, complexity)\n\n## Consequences\n\n### Positive\n\n1. **Simpler Code**: 2 backends instead of 4 reduces complexity by 50%\n2. **Faster Compilation**: Removing AWS SDK saves ~30 seconds compile time\n3. **Clear Guidance**: Age = dev, Cosmian = prod (no confusion)\n4. **Offline Development**: Age works without network connectivity\n5. **Better Security**: Cosmian provides confidential computing (TEE)\n6. **No Cloud Lock-in**: Not dependent on AWS infrastructure\n7. **Easier Testing**: Age backend requires no setup\n8. **Reduced Dependencies**: Fewer external crates to maintain\n\n### Negative\n\n1. **Migration Required**: Existing Vault/AWS KMS users must migrate\n2. **Learning Curve**: Teams must learn Age and Cosmian\n3. **Cosmian Dependency**: Production depends on Cosmian availability\n4. **Cost**: Cosmian may have licensing costs (cloud or self-hosted)\n\n### Neutral\n\n1. **Feature Parity**: Cosmian provides all features Vault/AWS had\n2. **API Compatibility**: Encrypt/decrypt API remains primarily the same\n3. **Configuration Change**: TOML config structure updated but similar\n\n## Implementation\n\n### Files Created\n\n1. `src/age/client.rs` (167 lines) - Age encryption client\n2. `src/age/mod.rs` (3 lines) - Age module exports\n3. `src/cosmian/client.rs` (294 lines) - Cosmian KMS client\n4. `src/cosmian/mod.rs` (3 lines) - Cosmian module exports\n5. `docs/migration/KMS_SIMPLIFICATION.md` (500+ lines) - Migration guide\n\n### Files Modified\n\n1. `src/lib.rs` - Updated exports (age, cosmian instead of aws, vault)\n2. `src/types.rs` - Updated error types and config enum\n3. `src/service.rs` - Simplified to 2 backends (180 lines, was 213)\n4. `Cargo.toml` - Removed AWS deps, added `age = "0.10"`\n5. `README.md` - Complete rewrite for new backends\n6. `provisioning/config/kms.toml` - Simplified configuration\n\n### Files Deleted\n\n1. `src/aws/client.rs` - AWS KMS client\n2. `src/aws/envelope.rs` - Envelope encryption helpers\n3. `src/aws/mod.rs` - AWS module\n4. `src/vault/client.rs` - Vault client\n5. `src/vault/mod.rs` - Vault module\n\n### Dependencies Changed\n\n**Removed**:\n\n- `aws-sdk-kms = "1"`\n- `aws-config = "1"`\n- `aws-credential-types = "1"`\n- `aes-gcm = "0.10"` (was only for AWS envelope encryption)\n\n**Added**:\n\n- `age = "0.10"`\n- `tempfile = "3"` (dev dependency for tests)\n\n**Kept**:\n\n- All Axum web framework deps\n- `reqwest` (for Cosmian HTTP API)\n- `base64`, `serde`, `tokio`, etc.\n\n## Migration Path\n\n### For Development\n\n```\n# 1. Install Age\nbrew install age  # or apt install age\n\n# 2. Generate keys\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# 3. Update config to use Age backend\n# 4. Re-encrypt development secrets\n```\n\n### For Production\n\n```\n# 1. Set up Cosmian KMS (cloud or self-hosted)\n# 2. Create master key in Cosmian\n# 3. Migrate secrets from Vault/AWS to Cosmian\n# 4. Update production config\n# 5. Deploy new KMS service\n```\n\nSee `docs/migration/KMS_SIMPLIFICATION.md` for detailed steps.\n\n## Alternatives Considered\n\n### Alternative 1: Keep All 4 Backends\n\n**Pros**:\n\n- No migration required\n- Maximum flexibility\n\n**Cons**:\n\n- Continued complexity\n- Maintenance burden\n- Unclear guidance\n\n**Rejected**: Complexity outweighs benefits\n\n### Alternative 2: Only Cosmian (No Age)\n\n**Pros**:\n\n- Single backend\n- Enterprise-grade everywhere\n\n**Cons**:\n\n- Requires Cosmian server for development\n- Slower dev iteration\n- Network dependency for local dev\n\n**Rejected**: Development experience matters\n\n### Alternative 3: Only Age (No Production Backend)\n\n**Pros**:\n\n- Simplest solution\n- No server required\n\n**Cons**:\n\n- Not suitable for production\n- No audit logging\n- No key rotation\n- No multi-tenant support\n\n**Rejected**: Production needs enterprise features\n\n### Alternative 4: Age + HashiCorp Vault\n\n**Pros**:\n\n- Vault is widely known\n- No Cosmian dependency\n\n**Cons**:\n\n- Vault lacks confidential computing\n- Vault server still required\n- No zero-knowledge architecture\n\n**Rejected**: Cosmian provides better security features\n\n## Metrics\n\n### Code Reduction\n\n- **Total Lines Removed**: ~800 lines (AWS + Vault implementations)\n- **Total Lines Added**: ~470 lines (Age + Cosmian + docs)\n- **Net Reduction**: ~330 lines\n\n### Dependency Reduction\n\n- **Crates Removed**: 4 (aws-sdk-kms, aws-config, aws-credential-types, aes-gcm)\n- **Crates Added**: 1 (age)\n- **Net Reduction**: 3 crates\n\n### Compilation Time\n\n- **Before**: ~90 seconds (with AWS SDK)\n- **After**: ~60 seconds (without AWS SDK)\n- **Improvement**: 33% faster\n\n## Compliance\n\n### Security Considerations\n\n1. **Age Security**: X25519 (Curve25519) encryption, modern and secure\n2. **Cosmian Security**: Confidential computing, zero-knowledge, enterprise-grade\n3. **No Regression**: Security features maintained or improved\n4. **Clear Separation**: Dev (Age) never used for production secrets\n\n### Testing Requirements\n\n1. **Unit Tests**: Both backends have comprehensive test coverage\n2. **Integration Tests**: Age tests run without external deps\n3. **Cosmian Tests**: Require test server (marked as `#[ignore]`)\n4. **Migration Tests**: Verify old configs fail gracefully\n\n## References\n\n- [Age Encryption](https://github.com/FiloSottile/age) - Modern encryption tool\n- [Cosmian KMS](https://cosmian.com/kms/) - Enterprise KMS with confidential computing\n- [ADR-006](adr-006-provisioning-cli-refactoring.md) - Previous KMS integration\n- [Migration Guide](../migration/KMS_SIMPLIFICATION.md) - Detailed migration steps\n\n## Notes\n\n- Age is designed by Filippo Valsorda (Google, Go security team)\n- Cosmian provides FIPS 140-2 Level 3 compliance (when using certified hardware)\n- This decision aligns with project goal of reducing cloud provider dependencies\n- Migration timeline: 6 weeks for full adoption