Skip to content

Manage Keys

Caracal uses separate keys for encryption, mandate signing, audit integrity, stream integrity, and service-to-service exchange.

Key Map

Material	Used by	Purpose
Zone signing keys	STS	Sign mandate JWTs and publish public keys through JWKS.
`ZONE_KEK`	API and STS	Encrypt/decrypt zone secrets and key material.
`AUDIT_HMAC_KEY`	API, STS, Gateway, Audit, Control	Protect audit event integrity.
`STREAMS_HMAC_KEY`	API, STS, Gateway, Coordinator, Audit/consumers	Sign Redis stream messages in published modes.
`GATEWAY_STS_HMAC_KEY`	Gateway and STS	Authenticate Gateway token-exchange requests to STS.
Admin and Coordinator tokens	API, Coordinator, Console, Control	Authenticate management and agent/delegation operations.

Mandate Verification

sequenceDiagram
  participant STS
  participant Client
  participant Resource
  STS->>Client: signed mandate JWT
  Resource->>STS: GET /.well-known/jwks.json
  STS-->>Resource: public keys with cache headers
  Client->>Resource: bearer mandate
  Resource->>Resource: verify signature, issuer, audience, scopes, token use, revocation

STS JWKS responses are cacheable; rotation plans must preserve overlap until verifier caches expire.

Gateway Exchange Signature

Gateway signs STS exchange requests with timestamp, request ID, method, path, and form body. STS checks the signature, skew, request ID, and nonce before accepting the Gateway-authenticated path.

Published-Mode Requirements

In rc and stable, HMAC keys used by services must be present and at least 32 bytes where validated. Missing keys cause startup or readiness failure rather than silent downgrade.

Next Step

Use Enforce Boundaries to connect keys, services, commands, and data stores to trust boundaries.