Crate secret_manager

Expand description

Distributed secret-key rotation and in-process caching.

§Overview

secret-manager manages a ring buffer of versioned encryption keys shared across a cluster. Keys are generated, encrypted, and persisted by a rotator; they are fetched, decrypted, and cached in memory by a syncer. The two roles are intentionally decoupled so you can deploy them in whatever topology fits your system.

§Core concepts

Concept	Type	Purpose
Key group	`GroupId`	Logical namespace for a set of rotating keys
Ring buffer	`InMemorySecretGroup<V, S>`	In-process cache; `V` slots, each key `S` bytes
Version	`u8`	Slot index (0 … V-1); wraps modulo V, not at 255
Rotator	`KeyRotator`	Background task — generates and stores new keys
Syncer	`SecretSyncer`	Background task — polls storage and updates the ring
Manager	`SecretManager`	Convenience facade that runs both together

§Usage patterns

§All-in-one: `SecretManager`

Use this when a single service instance should both rotate and consume keys:

let group = Arc::new(InMemorySecretGroup::<256, 32>::new(0, [0u8; 32]));

// `backend` implements both `SecretBackend` and `SecretRotationBackend`.
// `encryptor` implements `KeyEncryptor` (e.g. `LocalEncryptor`).
let manager = SecretManager::new(
    "payments-signing",
    Arc::clone(&group),
    backend,
    encryptor,
    Duration::from_secs(3600), // rotate every hour
    Duration::from_secs(30),   // propagation delay before activating a new key
    None,                      // poll interval (default: 5 s)
    None,                      // key generator (default: CSPRNG)
);

let token = CancellationToken::new();
let handle = manager.start(token.clone()).await?;

// Use `group.current()` to get the active signing key.
// Use `group.resolve(version)` to verify tokens issued with an older key.

token.cancel();
handle.wait().await; // wait for background tasks to stop cleanly

§Rotation-only: `KeyRotator`

Deploy a single dedicated rotation service that writes keys to storage while the rest of your fleet only reads them via syncers:

let rotator: KeyRotator<_, _, 256, 32> = KeyRotator::new(
    "session-tokens",
    backend,                   // implements `SecretRotationBackend`
    Duration::from_secs(3600),
    Duration::from_secs(30),
    encryptor,
    || [0u8; 32],
);
rotator.run(CancellationToken::new()).await;

§Read-only: `SecretSyncer`

Reader instances that never rotate — they only follow the key stream from storage:

let group = Arc::new(InMemorySecretGroup::<256, 32>::new(0, [0u8; 32]));
let mut syncer: SecretSyncer<_, _, 256, 32> = SecretSyncer::new(
    "api-tokens",
    Arc::clone(&group),
    backend,   // implements `SecretBackend`
    encryptor,
    Duration::from_secs(3600), // used to compute smart poll intervals
    None,                      // poll interval override
);

let token = CancellationToken::new();
let cursor = syncer.initial_load(&token).await?;
tokio::spawn(syncer.run(token, cursor));

§Encryptors

Type	Crate feature	Notes
`NoOpEncryptor`	(always)	Plaintext — testing / storage-layer encryption
`LocalEncryptor`	(always)	AES-256-GCM-SIV with a local 32-byte key
`KmsEncryptor`	`aws-kms`	AWS KMS — KMS manages the IV; requires network

§Backends

Type	Crate feature
`DieselPgSecretBackend`	`pg-diesel-async`
`SqlxPgSecretBackend`	`pg-sqlx`

Implement SecretBackend + SecretRotationBackend together to bring your own backend.

Structs§

DieselPgSecretBackend
Encrypted: An encrypted payload produced by a KeyEncryptor.
InMemorySecretGroup: An in-memory ring buffer of versioned secret keys, safe for concurrent use.
KeyRecord: A versioned secret key record as returned by a SecretBackend.
KeyRotator: Background task that periodically generates and persists a new encryption key.
KmsEncryptor: KeyEncryptor backed by AWS Key Management Service (KMS).
LocalEncryptor: KeyEncryptor that encrypts key material locally using AES-256-GCM-SIV.
NoOpEncryptor: A passthrough KeyEncryptor that stores key bytes as-is (no encryption).
SecretManager: Convenience facade that runs a SecretSyncer and a KeyRotator together.
SecretManagerHandle: Returned by SecretManager::start. Call wait after cancelling the CancellationToken to ensure both background tasks have fully stopped.
SecretSyncer: Background task that keeps an InMemorySecretGroup up-to-date by polling storage.
SqlxPgSecretBackend

Enums§

DieselPgSecretBackendError
EncryptorError: Errors returned by KeyEncryptor implementations.
SqlxPgSecretBackendError

Traits§

KeyEncryptor: Encrypts and decrypts key material before it is persisted to storage.
SecretBackend: Read-side storage contract used by SecretSyncer.
SecretGroup: A trait for versioned secret key groups.
SecretRotationBackend: Write-side storage contract required by KeyRotator.

Type Aliases§

GroupId: Identifies a logical group of rotating keys.