Control CoreDocs

Secured intercept and dual-custody secrets

Audience: Security architects / platform engineers
Time: ~25 min
Prerequisites: Cryptographic workload identity, at least one Bouncer registered, Helm or Custom deployment

Use this guide when the Bouncer must intercept TLS or mTLS traffic (on-prem VPC pilots, east-west service mesh, or agent-to-SaaS flows) without storing plaintext credentials in the Control Plane.

Dual-custody invariant

The Control Plane never decrypts customer upstream credentials. It stores envelope metadata only (key_id, opaque ciphertext_ref, optional AAD). The Bouncer resolves secrets at intercept time using workload identity (SPIRE SVID or cloud IAM).

Enable the feature in Settings → Feature Flags: flags.crypto.dual_custody_intercept (default off).

Step 1 — Choose a cryptographic provider (~5 min)

ProviderWhen to useControl Plane stores
KMS envelope (recommended for AWS)Customer CMK in AWS KMSCiphertext blob + key ARN
Vault delegateCustomer runs HashiCorp VaultSecret path + namespace reference

Detailed operator guides:

Configure via API (UI under Settings → Cryptographic Provider when flag is on):

curl -sS -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$CONTROL_PLANE_URL/v1/crypto/settings" \
  -d '{
    "provider": "kms_envelope",
    "kms_key_arn": "arn:aws:kms:ca-central-1:123456789012:key/abc-123",
    "notes": "Production CMK — dual custody"
  }'

Troubleshooting: 403 means the dual-custody flag is off. Enable it in Feature Flags first. See Troubleshooting.

Step 2 — Map endpoint secret paths (~10 min)

Register envelope metadata for each protected upstream credential path (no plaintext):

curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$CONTROL_PLANE_URL/v1/crypto/envelope-secrets" \
  -d '{
    "logical_path": "protected-resources/payments-api/upstream-tls",
    "key_id": "arn:aws:kms:ca-central-1:123456789012:key/abc-123",
    "ciphertext_ref": "AQICAHh...opaque-envelope-blob...",
    "aad": "env=production,bouncer=payments-east",
    "provider": "kms_envelope"
  }'

List mappings:

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CONTROL_PLANE_URL/v1/crypto/envelope-secrets"

Step 3 — Bouncer mTLS / TLS prerequisites (~5 min)

  1. Enable Cryptographic workload identity (SPIRE) or cloud IAM role for the Bouncer pod.
  2. Configure the protected resource protocol as HTTPS or mTLS in Bouncer Management.
  3. Ensure Policy Bridge sync is healthy — see Troubleshooting for the probe command.

For AI Pilot mTLS specifics see mTLS enforcement.

Step 4 — Verify intercept (~5 min)

curl -sS -H "Authorization: Bearer $TOKEN" \
  "$CONTROL_PLANE_URL/v1/bootstrap/status" | jq .

Send test traffic through the Bouncer listener. Audit should show decision events without decrypted payload or bearer tokens.

Security notes

  • Plaintext credentials must not appear in Control Plane API responses, audit exports, or persistent storage.
  • Rotate customer-managed keys on your schedule; re-wrap envelope metadata using your KMS or Vault procedures before updating registrations in the Control Plane.
  • Use only production-grade KMS or Vault endpoints in your environment — not shared lab or mock key services.

Next steps