# RustyVault KMS Backend Guide\n\n**Version**: 1.0.0\n**Date**: 2025-10-08\n**Status**: Production-ready\n\n---\n\n## Overview\n\nRustyVault is a self-hosted, Rust-based secrets management system that provides a **Vault-compatible API**. The provisioning platform now supports\nRustyVault as a KMS backend alongside Age, Cosmian, AWS KMS, and HashiCorp Vault.\n\n### Why RustyVault\n\n- **Self-hosted**: Full control over your key management infrastructure\n- **Pure Rust**: Better performance and memory safety\n- **Vault-compatible**: Drop-in replacement for HashiCorp Vault Transit engine\n- **OSI-approved License**: Apache 2.0 (vs HashiCorp's BSL)\n- **Embeddable**: Can run as standalone service or embedded library\n- **No Vendor Lock-in**: Open-source alternative to proprietary KMS solutions\n\n---\n\n## Architecture Position\n\n```\nKMS Service Backends:\n├── Age (local development, file-based)\n├── Cosmian (privacy-preserving, production)\n├── AWS KMS (cloud-native AWS)\n├── HashiCorp Vault (enterprise, external)\n└── RustyVault (self-hosted, embedded) ✨ NEW\n```\n\n---\n\n## Installation\n\n### Option 1: Standalone RustyVault Server\n\n```\n# Install RustyVault binary\ncargo install rusty_vault\n\n# Start RustyVault server\nrustyvault server -config=/path/to/config.hcl\n```\n\n### Option 2: Docker Deployment\n\n```\n# Pull RustyVault image (if available)\ndocker pull tongsuo/rustyvault:latest\n\n# Run RustyVault container\ndocker run -d \\n  --name rustyvault \\n  -p 8200:8200 \\n  -v $(pwd)/config:/vault/config \\n  -v $(pwd)/data:/vault/data \\n  tongsuo/rustyvault:latest\n```\n\n### Option 3: From Source\n\n```\n# Clone repository\ngit clone https://github.com/Tongsuo-Project/RustyVault.git\ncd RustyVault\n\n# Build and run\ncargo build --release\n./target/release/rustyvault server -config=config.hcl\n```\n\n---\n\n## Configuration\n\n### RustyVault Server Configuration\n\nCreate `rustyvault-config.hcl`:\n\n```\n# RustyVault Server Configuration\n\nstorage "file" {\n  path = "/vault/data"\n}\n\nlistener "tcp" {\n  address     = "0.0.0.0:8200"\n  tls_disable = true  # Enable TLS in production\n}\n\napi_addr = "http://127.0.0.1:8200"\ncluster_addr = "https://127.0.0.1:8201"\n\n# Enable Transit secrets engine\ndefault_lease_ttl = "168h"\nmax_lease_ttl = "720h"\n```\n\n### Initialize RustyVault\n\n```\n# Initialize (first time only)\nexport VAULT_ADDR='http://127.0.0.1:8200'\nrustyvault operator init\n\n# Unseal (after every restart)\nrustyvault operator unseal <unseal_key_1>\nrustyvault operator unseal <unseal_key_2>\nrustyvault operator unseal <unseal_key_3>\n\n# Save root token\nexport RUSTYVAULT_TOKEN='<root_token>'\n```\n\n### Enable Transit Engine\n\n```\n# Enable transit secrets engine\nrustyvault secrets enable transit\n\n# Create encryption key\nrustyvault write -f transit/keys/provisioning-main\n\n# Verify key creation\nrustyvault read transit/keys/provisioning-main\n```\n\n---\n\n## KMS Service Configuration\n\n### Update `provisioning/config/kms.toml`\n\n```\n[kms]\ntype = "rustyvault"\nserver_url = "http://localhost:8200"\ntoken = "${RUSTYVAULT_TOKEN}"\nmount_point = "transit"\nkey_name = "provisioning-main"\ntls_verify = true\n\n[service]\nbind_addr = "0.0.0.0:8081"\nlog_level = "info"\naudit_logging = true\n\n[tls]\nenabled = false  # Set true with HTTPS\n```\n\n### Environment Variables\n\n```\n# RustyVault connection\nexport RUSTYVAULT_ADDR="http://localhost:8200"\nexport RUSTYVAULT_TOKEN="s.xxxxxxxxxxxxxxxxxxxxxx"\nexport RUSTYVAULT_MOUNT_POINT="transit"\nexport RUSTYVAULT_KEY_NAME="provisioning-main"\nexport RUSTYVAULT_TLS_VERIFY="true"\n\n# KMS service\nexport KMS_BACKEND="rustyvault"\nexport KMS_BIND_ADDR="0.0.0.0:8081"\n```\n\n---\n\n## Usage\n\n### Start KMS Service\n\n```\n# With RustyVault backend\ncd provisioning/platform/kms-service\ncargo run\n\n# With custom config\ncargo run -- --config=/path/to/kms.toml\n```\n\n### CLI Operations\n\n```\n# Encrypt configuration file\nprovisioning kms encrypt provisioning/config/secrets.yaml\n\n# Decrypt configuration\nprovisioning kms decrypt provisioning/config/secrets.yaml.enc\n\n# Generate data key (envelope encryption)\nprovisioning kms generate-key --spec AES256\n\n# Health check\nprovisioning kms health\n```\n\n### REST API Usage\n\n```\n# Health check\ncurl http://localhost:8081/health\n\n# Encrypt data\ncurl -X POST http://localhost:8081/encrypt \\n  -H "Content-Type: application/json" \\n  -d '{\n    "plaintext": "SGVsbG8sIFdvcmxkIQ==",\n    "context": "environment=production"\n  }'\n\n# Decrypt data\ncurl -X POST http://localhost:8081/decrypt \\n  -H "Content-Type: application/json" \\n  -d '{\n    "ciphertext": "vault:v1:...",\n    "context": "environment=production"\n  }'\n\n# Generate data key\ncurl -X POST http://localhost:8081/datakey/generate \\n  -H "Content-Type: application/json" \\n  -d '{"key_spec": "AES_256"}'\n```\n\n---\n\n## Advanced Features\n\n### Context-based Encryption (AAD)\n\nAdditional authenticated data binds encrypted data to specific contexts:\n\n```\n# Encrypt with context\ncurl -X POST http://localhost:8081/encrypt \\n  -d '{\n    "plaintext": "c2VjcmV0",\n    "context": "environment=prod,service=api"\n  }'\n\n# Decrypt requires same context\ncurl -X POST http://localhost:8081/decrypt \\n  -d '{\n    "ciphertext": "vault:v1:...",\n    "context": "environment=prod,service=api"\n  }'\n```\n\n### Envelope Encryption\n\nFor large files, use envelope encryption:\n\n```\n# 1. Generate data key\nDATA_KEY=$(curl -X POST http://localhost:8081/datakey/generate \\n  -d '{"key_spec": "AES_256"}' | jq -r '.plaintext')\n\n# 2. Encrypt large file with data key (locally)\nopenssl enc -aes-256-cbc -in large-file.bin -out encrypted.bin -K $DATA_KEY\n\n# 3. Store encrypted data key (from response)\necho "vault:v1:..." > encrypted-data-key.txt\n```\n\n### Key Rotation\n\n```\n# Rotate encryption key in RustyVault\nrustyvault write -f transit/keys/provisioning-main/rotate\n\n# Verify new version\nrustyvault read transit/keys/provisioning-main\n\n# Rewrap existing ciphertext with new key version\ncurl -X POST http://localhost:8081/rewrap \\n  -d '{"ciphertext": "vault:v1:..."}'\n```\n\n---\n\n## Production Deployment\n\n### High Availability Setup\n\nDeploy multiple RustyVault instances behind a load balancer:\n\n```\n# docker-compose.yml\nversion: '3.8'\n\nservices:\n  rustyvault-1:\n    image: tongsuo/rustyvault:latest\n    ports:\n      - "8200:8200"\n    volumes:\n      - ./config:/vault/config\n      - vault-data-1:/vault/data\n\n  rustyvault-2:\n    image: tongsuo/rustyvault:latest\n    ports:\n      - "8201:8200"\n    volumes:\n      - ./config:/vault/config\n      - vault-data-2:/vault/data\n\n  lb:\n    image: nginx:alpine\n    ports:\n      - "80:80"\n    volumes:\n      - ./nginx.conf:/etc/nginx/nginx.conf\n    depends_on:\n      - rustyvault-1\n      - rustyvault-2\n\nvolumes:\n  vault-data-1:\n  vault-data-2:\n```\n\n### TLS Configuration\n\n```\n# kms.toml\n[kms]\ntype = "rustyvault"\nserver_url = "https://vault.example.com:8200"\ntoken = "${RUSTYVAULT_TOKEN}"\ntls_verify = true\n\n[tls]\nenabled = true\ncert_path = "/etc/kms/certs/server.crt"\nkey_path = "/etc/kms/certs/server.key"\nca_path = "/etc/kms/certs/ca.crt"\n```\n\n### Auto-Unseal (AWS KMS)\n\n```\n# rustyvault-config.hcl\nseal "awskms" {\n  region     = "us-east-1"\n  kms_key_id = "arn:aws:kms:us-east-1:123456789012:key/..."\n}\n```\n\n---\n\n## Monitoring\n\n### Health Checks\n\n```\n# RustyVault health\ncurl http://localhost:8200/v1/sys/health\n\n# KMS service health\ncurl http://localhost:8081/health\n\n# Metrics (if enabled)\ncurl http://localhost:8081/metrics\n```\n\n### Audit Logging\n\nEnable audit logging in RustyVault:\n\n```\n# rustyvault-config.hcl\naudit {\n  path = "/vault/logs/audit.log"\n  format = "json"\n}\n```\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n**1. Connection Refused**\n\n```\n# Check RustyVault is running\ncurl http://localhost:8200/v1/sys/health\n\n# Check token is valid\nexport VAULT_ADDR='http://localhost:8200'\nrustyvault token lookup\n```\n\n**2. Authentication Failed**\n\n```\n# Verify token in environment\necho $RUSTYVAULT_TOKEN\n\n# Renew token if needed\nrustyvault token renew\n```\n\n**3. Key Not Found**\n\n```\n# List available keys\nrustyvault list transit/keys\n\n# Create missing key\nrustyvault write -f transit/keys/provisioning-main\n```\n\n**4. TLS Verification Failed**\n\n```\n# Disable TLS verification (dev only)\nexport RUSTYVAULT_TLS_VERIFY=false\n\n# Or add CA certificate\nexport RUSTYVAULT_CACERT=/path/to/ca.crt\n```\n\n---\n\n## Migration from Other Backends\n\n### From HashiCorp Vault\n\nRustyVault is API-compatible, minimal changes required:\n\n```\n# Old config (Vault)\n[kms]\ntype = "vault"\naddress = "https://vault.example.com:8200"\ntoken = "${VAULT_TOKEN}"\n\n# New config (RustyVault)\n[kms]\ntype = "rustyvault"\nserver_url = "http://rustyvault.example.com:8200"\ntoken = "${RUSTYVAULT_TOKEN}"\n```\n\n### From Age\n\nRe-encrypt existing encrypted files:\n\n```\n# 1. Decrypt with Age\nprovisioning kms decrypt --backend age secrets.enc > secrets.plain\n\n# 2. Encrypt with RustyVault\nprovisioning kms encrypt --backend rustyvault secrets.plain > secrets.rustyvault.enc\n```\n\n---\n\n## Security Considerations\n\n### Best Practices\n\n1. **Enable TLS**: Always use HTTPS in production\n2. **Rotate Tokens**: Regularly rotate RustyVault tokens\n3. **Least Privilege**: Use policies to restrict token permissions\n4. **Audit Logging**: Enable and monitor audit logs\n5. **Backup Keys**: Secure backup of unseal keys and root token\n6. **Network Isolation**: Run RustyVault in isolated network segment\n\n### Token Policies\n\nCreate restricted policy for KMS service:\n\n```\n# kms-policy.hcl\npath "transit/encrypt/provisioning-main" {\n  capabilities = ["update"]\n}\n\npath "transit/decrypt/provisioning-main" {\n  capabilities = ["update"]\n}\n\npath "transit/datakey/plaintext/provisioning-main" {\n  capabilities = ["update"]\n}\n```\n\nApply policy:\n\n```\nrustyvault policy write kms-service kms-policy.hcl\nrustyvault token create -policy=kms-service\n```\n\n---\n\n## Performance\n\n### Benchmarks (Estimated)\n\n| Operation | Latency | Throughput |\n| ----------- | --------- | ------------ |\n| Encrypt | 5-15 ms | 2,000-5,000 ops/sec |\n| Decrypt | 5-15 ms | 2,000-5,000 ops/sec |\n| Generate Key | 10-20 ms | 1,000-2,000 ops/sec |\n\n*Actual performance depends on hardware, network, and RustyVault configuration*\n\n### Optimization Tips\n\n1. **Connection Pooling**: Reuse HTTP connections\n2. **Batching**: Batch multiple operations when possible\n3. **Caching**: Cache data keys for envelope encryption\n4. **Local Unseal**: Use auto-unseal for faster restarts\n\n---\n\n## Related Documentation\n\n- **KMS Service**: `docs/user/CONFIG_ENCRYPTION_GUIDE.md`\n- **Dynamic Secrets**: `docs/user/DYNAMIC_SECRETS_QUICK_REFERENCE.md`\n- **Security System**: `docs/architecture/adr-009-security-system-complete.md`\n- **RustyVault GitHub**: <https://github.com/Tongsuo-Project/RustyVault>\n\n---\n\n## Support\n\n- **GitHub Issues**: <https://github.com/Tongsuo-Project/RustyVault/issues>\n- **Documentation**: <https://github.com/Tongsuo-Project/RustyVault/tree/main/docs>\n- **Community**: <https://users.rust-lang.org/t/rustyvault-a-hashicorp-vault-replacement-in-rust/103943>\n\n---\n\n**Last Updated**: 2025-10-08\n**Maintained By**: Architecture Team
