Vapora/docs/adrs/0011-secretumvault.md

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:

// 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:

// Retrieve and decrypt
let api_key = secret_store
    .get_secret("anthropic_api_key")?
    .decrypt()
    .audit_log("anthropic_api_key_access", &user_id)?;

Audit Log:

// 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)