Skip to main content

Broker & attested_workload

Concept​

A caller shouldn't have to implement passport minting and request signing itself. The broker is a small local service that does it for them: a caller asks "let me call GET /orders," and the broker returns a request-bound passport + transcript-v1 proof over a pod-local Unix socket.

By default the broker signs with a local software key. On Kubernetes it can go further: verify the caller's SPIFFE/SPIRE X.509-SVID before issuing, and stamp the passport as attested_workload — the strongest signer class.

Implementation​

  • cmd/trustplane-broker + internal/broker; listens on a Unix domain socket (no broker Service, no TCP port exposed).
  • Software path (default): issues request-bound passport/stamp pairs from the locked broker IPC v1 JSON contract, signed with a local Ed25519 key. Records profile, signer: local/software, and same-host peer metadata (UID/GID/PID/process) only where the OS resolver safely provides it — otherwise unknown/unsupported (no overclaiming).
  • SPIFFE/SPIRE path: verifies X.509-SVID via a WorkloadIdentitySource. A concrete go-spiffe-backed SPIRE Workload API source is included, with explicit trustplane-broker flags for a live SPIRE socket. Profile: trustplane-spiffe-spire-k8s-v1.
  • Trust split: for protected requests, the verifier trusts the broker issuer key from the local bundle. The broker is the attestation authority; the verifier does not re-verify the SVID per request.

Example​

Issue a request-bound passport from the broker (CLI):

trustplane broker issue \
  --method GET \
  --path /orders \
  --audience acme.demo.orders \
  --route-id acme.demo.orders.read

Or run the whole local stack (broker + adapter + bundle) with one command:

trustplane up

The broker abuse regressions (wrong peer, wrong route, stale nonce, replay) each deny with a stable reason and an audit record, and run as part of the acceptance gate.

For the same-cluster SPIFFE/SPIRE M2M shape (broker sidecar + SPIRE Workload API CSI), see the deployment overview. Deployment examples should stay dry-run-first and avoid exposing provider-specific environment details.

The honest boundary on attested_workload​

  • attested_workload means "the broker verified workload identity (SVID) before issuance."
  • It does not mean the broker's signing key is hardware-backed, enclave-backed, KMS-backed, or non-exportable.
  • The verifier trusts the broker issuer key from the bundle and does not re-verify the SVID on each request.
  • The v0.1 runtime path is intentionally narrow: X.509-SVID only, configured profile only, local trust-domain + SPIFFE-ID allow checks, fail-closed when the SPIRE Workload API or pod binding can't be verified. No JWT-SVID, no Helm-packaged SPIRE, no hardware/enclave/KMS signer.

→ Next: Audit events.