Module kms 

Key Management Service (KMS) abstraction.

Provides a vendor-agnostic interface for external KMS integration:

• AWS KMS - Amazon’s managed KMS
• HashiCorp Vault - Open-source secrets management
• GCP Cloud KMS - Google’s managed KMS
• Azure Key Vault - Microsoft’s managed KMS
• Local/Env - For development only (keys from environment)

Architecture

This module uses envelope encryption:

┌─────────────────────────────────────────────────────────────┐
│                    Envelope Encryption                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐     encrypts      ┌──────────┐                │
│  │  Master  │  ─────────────▶   │   Data   │                │
│  │   Key    │                   │Encryption│                │
│  │  (KEK)   │  ◀─────────────   │   Key    │                │
│  └──────────┘     decrypts      │  (DEK)   │                │
│       │                         └──────────┘                │
│       │ stored in                    │                      │
│       ▼                              │ encrypts             │
│  ┌──────────┐                        ▼                      │
│  │   KMS    │                   ┌──────────┐                │
│  │(AWS/GCP/ │                   │   Data   │                │
│  │ Vault)   │                   │(metadata,│                │
│  └──────────┘                   │ API keys)│                │
│                                 └──────────┘                │
└─────────────────────────────────────────────────────────────┘

Benefits of envelope encryption:

1. Master key never leaves KMS (hardware-backed security)
2. DEKs can be cached locally (reduced latency)
3. Key rotation only requires re-encrypting DEKs, not all data
4. Reduced KMS API calls (cost optimization)

Security Properties

• Master keys are stored in external KMS (never in memory long-term)
• DEKs are cached with configurable TTL (default: 5 minutes)
• All key material uses SecretBytes with zeroize-on-drop
• Key versioning supports seamless rotation
• All operations are instrumented with tracing spans
• Retry logic with exponential backoff for transient failures

Structs

CacheStats

Cache statistics for monitoring.

CachedKms

Cached wrapper around a KMS provider.

CircuitBreakerConfig

Configuration for circuit breaker behavior.

CircuitBreakerKms

Circuit breaker wrapper around a KMS provider.

DataEncryptionKey

Data Encryption Key (DEK) with metadata.

EncryptedEnvelope

Helper for envelope encryption operations.

EncryptionContext

Encryption context provides additional authenticated data (AAD).

EnvKeyProvider

KMS provider that loads keys from environment variables.

KeyRotationManager

Manager for coordinating key rotation across the system.

KeyRotationResult

Result of a key rotation operation.

KmsAuditEvent

Audit event for KMS operations.

KmsCacheConfig

Configuration for KMS caching.

KmsMetrics

Metrics for KMS operations.

KmsMetricsSnapshot

Snapshot of KMS metrics at a point in time.

ResilientKmsConfig

Configuration for a production-grade resilient KMS stack.

RetryConfig

Configuration for retry behavior on transient KMS failures.

RetryKms

KMS wrapper that adds retry logic with exponential backoff.

Enums

CircuitState

State of the circuit breaker.

KmsConfig

Configuration for KMS providers.

KmsError

Errors that can occur during KMS operations.

KmsOperation

Types of KMS operations for auditing.

VaultAuth

Vault authentication methods.

Traits

KeyManagementService

Key Management Service trait.

Functions

create_kms

Creates a KMS provider from configuration.

create_resilient_kms

Creates a resilient KMS stack with layered protection.

Type Aliases

Result