## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# ADR-011: SecretumVault para Secrets Management

Status: Accepted | Implemented Date: 2024-11-01 Deciders: Security Architecture Team Technical Story: Securing API keys and credentials with post-quantum cryptography

## Decision

Usar SecretumVault para gestión de secrets con criptografía post-quantum (no HashiCorp Vault, no plain K8s secrets).

## Rationale

1. Post-Quantum Cryptography: Protege contra ataques futuros con quantum computers
2. Rust-Native: Sin dependencias externas, compila a binario standalone
3. API Key Security: Encriptación at-rest para LLM API keys
4. Audit Logging: Todas las operaciones de secretos registradas
5. Future-Proof: Prepara a VAPORA para amenazas de seguridad del futuro

## Alternatives Considered

### ❌ HashiCorp Vault

- Pros: Maduro, enterprise-grade
- Cons: Externa dependencia, operacional overhead, no post-quantum

### ❌ Kubernetes Secrets

- Pros: Built-in, simple
- Cons: Almacenamiento by default sin encripción, no audit logging

### ✅ SecretumVault (CHOSEN)

- Post-quantum cryptography, Rust-native, audit-friendly

## Trade-offs

Pros:

- ✅ Post-quantum resistance for future threats
- ✅ Built-in audit logging of secret access
- ✅ Rust-native (no external dependencies)
- ✅ Encryption at-rest for API keys
- ✅ Fine-grained access control

Cons:

- ⚠️ Smaller community than HashiCorp Vault
- ⚠️ Fewer integrations with external tools
- ⚠️ Post-quantum crypto adds computational overhead

## Implementation

Secret Storage:

    #![allow(unused)]
    fn main() {
    // crates/vapora-backend/src/secrets.rs
    use secretumvault::SecretStore;

    let secret_store = SecretStore::new()?;

    // Store API key with encryption
    secret_store.store_secret(
        "anthropic_api_key",
        "sk-ant-...",
        SecretMetadata {
            encrypted: true,
            pq_algorithm: "ML-KEM-768",  // Post-quantum algorithm
            owner: "llm-router",
            created_at: Utc::now(),
        }
    )?;
    }

Secret Retrieval:

    #![allow(unused)]
    fn main() {
    // Retrieve and decrypt
    let api_key = secret_store
        .get_secret("anthropic_api_key")?
        .decrypt()
        .audit_log("anthropic_api_key_access", &user_id)?;
    }

Audit Log:

    #![allow(unused)]
    fn main() {
    // All secret operations logged
    secret_store.audit_log().query()
        .secret("anthropic_api_key")
        .since(Duration::days(1))
        .await?
        // Returns: Who accessed what secret when
    }

Configuration:

    # config/secrets.toml
    [secretumvault]
    store_path = "/etc/vapora/secrets.db"
    pq_algorithm = "ML-KEM-768"  # Post-quantum
    rotation_days = 90
    audit_retention_days = 365

    [[secret_categories]]
    name = "api_keys"
    encryption = true
    rotation_required = true

    [[secret_categories]]
    name = "database_credentials"
    encryption = true
    rotation_required = true

Key Files:

- `/crates/vapora-backend/src/secrets.rs` (secret management)
- `/crates/vapora-llm-router/src/providers.rs` (uses secrets to load API keys)
- `/config/secrets.toml` (configuration)

## Verification

    # Test secret storage and retrieval
    cargo test -p vapora-backend test_secret_storage

    # Test encryption/decryption
    cargo test -p vapora-backend test_secret_encryption

    # Verify audit logging
    cargo test -p vapora-backend test_audit_logging

    # Test key rotation
    cargo test -p vapora-backend test_secret_rotation

    # Verify post-quantum algorithms
    cargo test -p vapora-backend test_pq_algorithms

    # Integration test: load API key from secret store
    cargo test -p vapora-llm-router test_provider_auth -- --nocapture

Expected Output:

- Secrets stored encrypted with post-quantum algorithm
- Decryption works correctly
- All secret access logged with timestamp, user, resource
- Key rotation works automatically
- API keys loaded securely in providers
- No keys leak in logs or error messages

## Consequences

### Security Operations

- Secret rotation automated every 90 days
- Audit logs accessible for compliance investigations
- Break-glass procedures for emergency access (logged)
- All secret operations require authentication

### Performance

- Secret retrieval cached (policies don't change)
- Decryption overhead < 1ms per secret
- Audit logging asynchronous (doesn't block requests)

### Maintenance

- Post-quantum algorithms updated as standards evolve
- Audit logs must be retained per compliance policy
- Key rotation scheduled and tracked

### Compliance

- Audit trail for regulatory investigations
- Encryption meets security standards
- Post-quantum protection for long-term security

## References

- SecretumVault Documentation
- Post-Quantum Cryptography (ML-KEM)
- `/crates/vapora-backend/src/secrets.rs` (integration code)
- `/config/secrets.toml` (configuration)

Related ADRs: ADR-009 (Istio), ADR-025 (Multi-Tenancy)