Architecture¶
Components¶
- Your application (SDK) — encrypts/decrypts secret values locally, and signs every request to the server with your AWS identity.
- AWS STS — used only to prove identity (
GetCallerIdentity); never issues a shared token that is stored anywhere. - AWS KMS — a key in your own AWS account performs the actual
Encrypt/Decryptcalls. The server has no access to this key. - CPS-Vault server — a small stateless service that verifies identity proofs and stores/serves ciphertext plus catalog metadata.
- AWS WAF + API Gateway — the only public entry point is the custom domain
cps-vault.commandcentral.com. A WAF applies AWS managed rules and a per-IP rate limit before the request reaches the API.
Request flow¶
flowchart LR
subgraph Caller["Your process (SDK)"]
A[VaultSDK.create / put / fetch] --> B[Sign STS GetCallerIdentity request]
A --> C[Encrypt / decrypt via local KMS client]
end
B -->|X-Identity-Proof header| W[WAF + API Gateway]
W --> D[CPS-Vault Server]
D -->|forward proof| E[AWS STS]
E -->|identity verified| D
D -->|store / return ciphertext + metadata| A
C <-->|Encrypt / Decrypt| F[AWS KMS - your account]
Write path (create / put)¶
- SDK encrypts the plaintext locally via
KmsHelper(creating the KMS key by alias on first use if needed). - SDK signs a
GetCallerIdentityrequest against the server's regional STS endpoint (us-east-1, regardless of your own region) and bundles it into theX-Identity-Proofheader. - SDK sends the ciphertext + metadata (application name, project name, TTL, description) to the server through the WAF and API Gateway.
- Server forwards the identity proof to AWS STS to confirm the caller's identity, then persists the record.
Read path (fetch)¶
- SDK sends a signed
GETrequest for the secret name. - Server verifies identity, looks up the record, and returns the stored ciphertext.
- SDK decrypts the ciphertext locally via KMS using the caller's own credentials — the server is never involved in decryption.
Deployment topology¶
flowchart LR
C[SDK / caller<br/>any AWS account, any region] -->|HTTPS<br/>cps-vault.commandcentral.com| DNS[DNS CNAME]
DNS --> DOM[API Gateway custom domain<br/>TLS 1.2]
DOM --> WAF[AWS WAFv2 WebACL<br/>managed rules + per-IP rate limit]
WAF --> API[API Gateway REST API<br/>stage throttling]
API -->|/secrets| S[SecretsFunction<br/>Lambda, VPC]
API -->|/docs| D[DocsFunction<br/>Lambda, static site]
S -->|verify X-Identity-Proof| STS[STS us-east-1]
S --> DDB[(DynamoDB)]
Identity is verified by the server itself: it forwards your signed identity proof to AWS STS, so
any valid AWS principal from any account can call the API without extra IAM permissions. Requests
over the limits return 429 Too many requests (WAF per-IP limit or API Gateway throttling). If STS
does not answer in time the server returns 503.
Storage & expiry¶
Secrets are stored server-side keyed by secret name, along with:
application_name/cpsprojectname— ownership metadata used bylist_secrets().ttl— a short-hand duration ("10m","6h","30d","2w","3mo","1y") converted to an expiry timestamp. Once a secret's TTL lapses, the storage layer removes it automatically — there is no manual cleanup step.
Key rotation¶
The encryption key used for client-side envelope encryption rotates automatically on a fixed schedule (annually, by default) once created — no manual re-encryption, redeployment, or downtime. Rotation is transparent to callers: existing ciphertext continues to decrypt correctly against prior key material, and new encryptions use the current key version automatically.
Why this design is fast and secure¶
- No token-vending round trip. Unlike systems that first fetch a temporary token/credential from the server and then use it, CPS-Vault authenticates the actual request directly — one round trip, not two.
- No decryption key ever traverses the network. Encrypt/decrypt calls happen directly between your process and your account's key management service; the CPS-Vault server is not in that call path at all.
- Nothing to rotate by hand. There's no CPS-Vault-issued API key or password to leak or revoke — access is entirely governed by your existing cloud identity and key policy, and the encryption key itself rotates on its own.