# Hybrid Key Management System (KMS)

A comprehensive hybrid KMS system built for the control center, supporting local/remote/hybrid modes
with intelligent caching, failover, and advanced security features.

## Architecture Overview

### Core Components

1. **KMS Backends**
   - **Local Backend**: SQLite with AES-256-GCM encryption
   - **Remote Backend**: Cosmian KMS client integration
   - **Hybrid Backend**: Intelligent combination of local and remote

2. **Caching System**
   - **Memory Cache**: In-memory LRU cache with TTL
   - **Redis Cache**: Distributed caching with automatic failover
   - **Local File Cache**: Persistent file-based cache for offline scenarios

3. **Security Features**
   - **Encryption**: AES-256-GCM for local storage
   - **Key Derivation**: HKDF-SHA256 for master key derivation
   - **Authentication**: Multiple auth methods (certificate, token, basic, OAuth)
   - **Audit Logging**: Comprehensive audit trail for all operations

4. **Advanced Features**
   - **Credential Management**: Automatic injection for cloud providers
   - **Key Rotation**: Configurable automatic key rotation
   - **HSM Integration**: Hardware Security Module support
   - **Zero-Knowledge Proofs**: For sensitive operations
   - **Migration Tools**: Backend-to-backend key migration

## Configuration

### TOML Configuration Example

```toml
[kms]
# Operation mode: local, remote, or hybrid
mode = "hybrid"

# Local SQLite backend configuration
[kms.local]
database_path = "./data/kms.db"

[kms.local.master_key]
derivation_method = "hkdf"
source = "generated"
iterations = 100000

[kms.local.encryption]
default_algorithm = "AES-256-GCM"
key_size_bits = 256
authenticated = true

[kms.local.backup]
enabled = true
backup_dir = "./backups/kms"
interval_hours = 24
max_backups = 7
compress = true
encrypt = true

# Remote Cosmian KMS configuration
[kms.remote]
server_url = "https://kms.example.com:9998"
auth_method = "certificate"
client_cert_path = "./certs/client.crt"
client_key_path = "./certs/client.key"
ca_cert_path = "./certs/ca.crt"
timeout_seconds = 30
verify_ssl = true

[kms.remote.retry]
max_attempts = 3
initial_delay_ms = 1000
max_delay_ms = 30000
backoff_multiplier = 2.0

# Cache configuration
[kms.cache]
enabled = true
backend = "memory"
default_ttl_seconds = 3600
max_size_bytes = 104857600  # 100MB
local_dir = "./cache/kms"

# Credential management
[kms.credentials]
enabled = true

[kms.credentials.storage]
storage_type = "sqlite"
encryption_key_id = "credential_encryption_key"
database_path = "./data/credentials.db"

[kms.credentials.providers.aws]
name = "AWS"
provider_type = "aws"
refresh_interval_seconds = 3600
expiry_warning_seconds = 300
regions = ["us-east-1", "eu-west-1"]

[kms.credentials.providers.upcloud]
name = "UpCloud"
provider_type = "upcloud"
refresh_interval_seconds = 3600
expiry_warning_seconds = 300
regions = ["fi-hel1", "us-nyc1"]

# Key rotation configuration
[kms.rotation]
enabled = true
interval_seconds = 2592000  # 30 days
max_age_seconds = 7776000   # 90 days
notice_seconds = 604800     # 7 days
schedule = "0 2 * * 0"      # Every Sunday at 2 AM

# Audit configuration
[kms.audit]
enabled = true
backend = "file"
retention_days = 90
log_level = "info"
include_data = false
max_file_size_mb = 100
format = "json"

# HSM configuration
[kms.hsm]
enabled = false
hsm_type = "pkcs11"
pkcs11_library = "/usr/lib/libpkcs11.so"
slot_id = 0

# Zero-knowledge proof configuration
[kms.zkp]
enabled = false
proof_system = "groth16"
setup_params_path = "./zkp/setup.params"

# Security policy
[kms.security]
require_strong_auth = true
min_key_length_bits = 256
max_key_age_days = 90
enable_pfs = true
allowed_algorithms = ["AES-256-GCM", "ChaCha20Poly1305", "RSA-4096", "ECDSA-P384"]
blocked_algorithms = ["DES", "3DES", "RC4", "MD5"]
policy_enforcement = "strict"
```

## Usage Examples

### Basic KMS Operations

```bash
use control_center::kms::{KmsManager, KmsConfig, KeyData, KeyType, KeyAlgorithm, KeyUsage};

// Initialize KMS manager
let config = KmsConfig::load_from_file("kms.toml").await?;
let mut kms = KmsManager::new(&config).await?;
kms.initialize().await?;

// Create a new encryption key
let key_data = KeyData {
    key_id: "my-encryption-key".to_string(),
    key_type: KeyType::Symmetric,
    algorithm: KeyAlgorithm::Aes256Gcm,
    usage: KeyUsage {
        encrypt: true,
        decrypt: true,
        ..Default::default()
    },
    key_size: 256,
    key_material: SecretBytes::new(generate_random_key(32)),
    metadata: KeyMetadata {
        name: Some("Application Encryption Key".to_string()),
        description: Some("Key for encrypting application data".to_string()),
        owner: Some("app-service".to_string()),
        environment: Some("production".to_string()),
        ..Default::default()
    },
    created_at: Utc::now(),
    last_accessed: None,
    expires_at: Some(Utc::now() + chrono::Duration::days(90)),
    status: KeyStatus::Active,
    tags: HashMap::from([
        ("purpose".to_string(), "encryption".to_string()),
        ("service".to_string(), "app".to_string()),
    ]),
};

// Store the key
let stored_key_id = kms.store_key(key_data).await?;
println!("Key stored with ID: {}", stored_key_id);

// Encrypt data
let plaintext = b"sensitive data to encrypt";
let context = HashMap::from([
    ("service".to_string(), "app".to_string()),
    ("version".to_string(), "1.0".to_string()),
]);
let ciphertext = kms.encrypt(&stored_key_id, plaintext, Some(context.clone())).await?;

// Decrypt data
let decrypted = kms.decrypt(&stored_key_id, &ciphertext, Some(context)).await?;
assert_eq!(plaintext, decrypted.as_slice());

// Get key information
if let Some(key_info) = kms.get_key(&stored_key_id).await? {
    println!("Key algorithm: {:?}", key_info.algorithm);
    println!("Key status: {:?}", key_info.status);
    println!("Created: {}", key_info.created_at);
}
```

### Provider Credential Management

```bash
use control_center::kms::{ProviderCredentials, CredentialType};

// Store AWS credentials
let aws_creds = ProviderCredentials {
    provider: "aws".to_string(),
    credential_type: CredentialType::AccessKey,
    access_key: "AKIAIOSFODNN7EXAMPLE".to_string(),
    secret_key: SecretBytes::new(b"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY".to_vec()),
    session_token: None,
    region: Some("us-east-1".to_string()),
    config: HashMap::new(),
    expires_at: Some(Utc::now() + chrono::Duration::hours(12)),
    created_at: Utc::now(),
};

kms.store_provider_credentials("aws", aws_creds).await?;

// Retrieve credentials for automatic injection
if let Some(creds) = kms.get_provider_credentials("aws").await? {
    println!("AWS Access Key: {}", creds.access_key);
    // Credentials are automatically injected into environment variables
    // or configuration files based on the injection configuration
}
```

### Health Monitoring

```bash
// Check system health
let health = kms.health_check().await?;
println!("KMS Health: {}", health.overall);
println!("Backend Status: {}", health.backend.healthy);
println!("Rotation Status: {}", health.rotation.healthy);
println!("Credentials Status: {}", health.credentials.healthy);

// Get cache statistics
let cache_stats = kms.cache.stats().await;
println!("Cache hit rate: {:.2}%", cache_stats.hit_rate() * 100.0);
println!("Cache entries: {}", cache_stats.entry_count);
```

## Integration with Existing System

### Environment Variable Integration

The KMS system integrates with the existing environment-based configuration:

```toml
# Set KMS configuration environment
export PROVISIONING_KMS_MODE=hybrid
export PROVISIONING_KMS_LOCAL_DATABASE_PATH=/var/lib/provisioning/kms.db
export PROVISIONING_KMS_REMOTE_SERVER_URL=https://kms.example.com:9998
export PROVISIONING_KMS_CACHE_ENABLED=true
```

### TOML Configuration Integration

Add KMS configuration to your existing `config.defaults.toml`:

```toml
# Extend existing configuration with KMS section
[kms]
mode = "local"  # Start with local mode
local.database_path = "{{paths.base}}/data/kms.db"
cache.enabled = true
cache.local_dir = "{{paths.base}}/cache/kms"
audit.enabled = true
```

### Nushell Integration

```nushell
# Load KMS configuration
def kms_config [] {
    let config_path = $"($env.PROVISIONING_BASE)/config.toml"
    open $config_path | get kms
}

# Check KMS health
def kms_health [] {
    http get http://localhost:8080/kms/health | from json
}

# List available keys
def kms_keys [] {
    http get http://localhost:8080/kms/keys | from json
}
```

## Security Considerations

### Key Storage Security

1. **Local Storage**: Keys are encrypted using AES-256-GCM with keys derived from a master key using HKDF
2. **Remote Storage**: Relies on Cosmian KMS security guarantees
3. **Cache**: Cached keys have TTL and are encrypted in transit
4. **Memory**: Key material is zeroed on drop using the `zeroize` crate

### Access Control

1. **Authentication**: Multiple authentication methods supported
2. **Authorization**: Key usage permissions enforced
3. **Audit**: All operations logged with detailed context
4. **Network**: TLS encryption for all remote communications

### Compliance Features

1. **Audit Trail**: Comprehensive logging of all KMS operations
2. **Key Rotation**: Automatic rotation with configurable policies
3. **Retention**: Configurable key and audit log retention
4. **Export Controls**: Keys can be marked as non-exportable

## Deployment Guide

### Production Deployment

1. **Configuration**:

   ```toml
   [kms]
   mode = "hybrid"

   [kms.security]
   policy_enforcement = "strict"
   require_strong_auth = true

   [kms.audit]
   enabled = true
   backend = "database"
   retention_days = 365
   ```

2. **Infrastructure**:
   - Dedicated KMS database server
   - Redis cluster for caching
   - HSM for high-security keys
   - Backup and disaster recovery

3. **Monitoring**:
   - Health check endpoints
   - Metrics collection
   - Alert on key expiration
   - Audit log monitoring

### Development Setup

1. **Local Development**:

   ```toml
   [kms]
   mode = "local"

   [kms.security]
   policy_enforcement = "permissive"

   [kms.audit]
   enabled = true
   backend = "stdout"
   ```

2. **Testing**:

   ```bash
   # Run with test configuration
   PROVISIONING_ENV=test ./control-center
   ```

## Performance Optimization

### Caching Strategy

1. **Multi-level Caching**: Memory → Redis → Local File
2. **TTL Management**: Configurable per key type
3. **Cache Warming**: Preload frequently used keys
4. **Eviction Policies**: LRU with size-based eviction

### Connection Pooling

1. **Database Connections**: Configurable pool size
2. **HTTP Connections**: Keep-alive and connection reuse
3. **Batch Operations**: Bulk key operations where supported

## Troubleshooting

### Common Issues

1. **Connection Failures**: Check network connectivity and certificates
2. **Permission Errors**: Verify file system permissions for local storage
3. **Cache Misses**: Monitor cache hit rates and adjust TTL
4. **Key Rotation**: Check rotation scheduler logs

### Debug Mode

```bash
# Enable debug logging
export PROVISIONING_DEBUG=true
export PROVISIONING_LOG_LEVEL=debug

# Run with verbose output
./control-center --debug
```

### Health Checks

```bash
# Check KMS health
curl http://localhost:8080/kms/health

# Check individual components
curl http://localhost:8080/kms/health/backend
curl http://localhost:8080/kms/health/cache
curl http://localhost:8080/kms/health/rotation
```

## Future Enhancements

### Planned Features

1. **Multi-Region Support**: Cross-region key replication
2. **Key Versioning**: Multiple versions per key with rollback
3. **Policy Engine**: Fine-grained access control policies
4. **Metrics Dashboard**: Web UI for monitoring and management
5. **Integration APIs**: REST and gRPC APIs for external systems

### Experimental Features

1. **Zero-Knowledge Proofs**: For privacy-preserving operations
2. **Quantum-Resistant Algorithms**: Post-quantum cryptography support
3. **Federated KMS**: Multi-organization key sharing
4. **Blockchain Integration**: Immutable audit trails

This hybrid KMS system provides a solid foundation for secure key management in the control center architecture,
with room for future enhancements and customization based on specific requirements.
