Key Manager Architecture - Polystack Documentation

Overview

The Key Manager service separates the API layer from the secret store backend, allowing the encryption backend to be swapped or scaled independently. Secret payloads are never stored in the metadata database — only encrypted references. The actual ciphertext resides exclusively in the configured secret store backend.

Service Topology

Component Descriptions

Component	Role	Port
Key Manager API	REST API for secrets, containers, orders, ACLs	9311
Key Manager Worker	Orchestrates secret lifecycle and CA plugin communication	Internal
Metadata DB	Stores secret references, container metadata, ACLs — no secret payloads	Internal
Secret Store Backend	Stores encrypted secret ciphertext	Varies by backend
CA Plugin	Integrates with Certificate Authorities for automated certificate issuance	Internal

Secret Storage Flow

Security Separation

The metadata database contains only encrypted references and ACL metadata — never plaintext secret payloads. Even if the metadata database is compromised, secret payloads cannot be extracted without also compromising the secret store backend.

Data	Location	Contains
Secret metadata	Metadata DB	Name, type, content type, expiration, ACLs
Secret payload	Secret store backend	Encrypted ciphertext only
Encryption keys	Secret store backend	Master wrapping keys (HSM) or key files (simple)

Next Steps

Backend Configuration

Configure simple crypto, PKCS#11, and KMIP backends

Secret Stores

Manage multiple backends and per-project store assignments

Security

Harden the Key Manager service and protect master keys

Troubleshooting

Diagnose and resolve Key Manager platform issues