Tenant KMS (BYOK) Overview

By default every KnoxCall tenant’s master key is wrapped by the platform’s own MASTER_KEY_B64. That’s strong isolation, but the wrapping key lives on KnoxCall’s infrastructure. Tenant KMS lets you go a step further: the wrapping key lives in your cloud account. KnoxCall is granted a narrow IAM permission to call Encrypt / Decrypt against that one key — nothing else. Revoke the grant and KnoxCall can no longer unwrap on the next cache miss. The tenant enters the sealed state on that next miss — up to one hour later, since the unwrapped master key is cached for one hour.

How it differs from Operator KMS

There are three wrapping options:

Wrap method	Who holds the wrapping key	Kill-switch location
`global`	KnoxCall (env var)	None — contact support
`operator_kms`	KnoxCall-managed KMS key	None — contact support
`customer_kms` (BYOK)	Your AWS / GCP / Azure account	Your IAM console

BYOK is Customer KMS. The Tenant KMS dashboard manages it.

When to use it

Regulatory requirement — FedRAMP, HIPAA, HITRUST, EU data residency frameworks that require customer-controlled key material
Kill-switch requirement — need to instantly revoke KnoxCall’s access to tenant data without contacting support
Audit requirement — need your own KMS audit log to record every unwrap call KnoxCall makes

BYOK tenants have a 5-minute agent session window, not the standard 1 hour. Agent sessions renew more frequently so that a revoked KMS grant caps in-flight plaintext exposure at roughly 5 minutes. Plan for this if you run long-lived self-hosted proxy deployments. (This is the agent session TTL — the in-process master-key cache TTL is 1 hour for all tenants.)

Architecture

KMS is not in the path of every encrypt/decrypt — only on a cache miss:

Incoming request
    ↓
KnoxCall proxy needs tenant master key
    ↓
Cache HIT → use cached key (valid for 1 hour)
Cache MISS → call customer KMS via IAM → unwrap master key → cache for 1 hour
    ↓
Encrypt / decrypt with master key (local, fast)

This means one KMS round-trip per 1-hour window, not per request.

Key version states

State	Meaning
`active`	Current version. New wraps use this. One per tenant at a time.
`retired`	Older version — still unwraps legacy ciphertext, no new wraps.
`revoked`	Cryptographic erasure. Data wrapped by this version is permanently unreadable.

Prerequisites

Owner or Admin role on the tenant
Provider IAM set up before onboarding — KnoxCall validates the grant at onboarding time

Static long-lived credentials (AWS access keys, GCP service account JSON key files) are rejected at the API level. AWS uses cross-account STS role assumption; GCP uses service account impersonation; Azure uses a client secret env var or Managed Identity. No credential value is ever stored in the database.

Onboarding (POST /admin/tenant-kms) does not require a step-up verification. Step-up is only required for sensitive post-onboard operations: unseal (2-minute window) and rotate (5-minute window).

Quick start

Before saving, KnoxCall runs a probe: wrap then unwrap 32 test bytes against your KMS key. If the IAM grant isn’t working, the request fails immediately and nothing is written to the database. Calling this endpoint when a KMS config already exists replaces it (UPSERT) — the probe runs first; if it fails, the existing config is unchanged.

curl -X POST https://admin.knoxcall.com/admin/tenant-kms \
  -H "Authorization: Bearer $KC_ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "aws",
    "kms_key_ref": "arn:aws:kms:us-east-1:111122223333:key/abcd-1234-...",
    "config": {
      "region": "us-east-1",
      "role_arn": "arn:aws:iam::111122223333:role/KnoxCallKMSAccess",
      "external_id": "your-chosen-external-id"
    }
  }'

For the full setup flow for each provider, see the pages below.

Cache architecture

The master key is cached in-process on the KnoxCall control plane — not per-agent and not in Redis. Cache key: <tenant_id>:active, TTL 1 hour (DEFAULT_CACHE_TTL_MS) for all tenants. Concurrent cache misses for the same tenant are deduplicated: a single KMS call is made and the result is shared to all waiters. This means KnoxCall makes roughly one KMS call per 1-hour window per tenant, regardless of agent count.

Sealed state

If KnoxCall can’t reach your KMS (IAM revoked, network partition, key disabled), the tenant enters the sealed state. New agent sessions fail with 503 Service Unavailable. In-flight agents with a valid session continue operating until their session expires (at most 5 minutes for BYOK tenants). See Sealed state and unseal for recovery steps.

AWS KMS setup

Cross-account IAM role + STS assumption

GCP Cloud KMS setup

Service account impersonation — no JSON key files

Azure Key Vault setup

Managed Identity or Federated Credentials

Sealed state and unseal

What happens when KMS is unreachable, and how to recover

Key rotation

Rotate your tenant master key under a new KMS-backed version

Key Management concepts

Background on global / operator_kms / customer_kms wrapping options

BYOK and KMS providers

Tenant KMS: AWS KMS setup

​Tenant KMS (BYOK) Overview

​How it differs from Operator KMS

​When to use it

​Architecture

​Key version states

​Prerequisites

​Quick start

​Cache architecture

​Sealed state

AWS KMS setup

GCP Cloud KMS setup

Azure Key Vault setup

Sealed state and unseal

Key rotation

Key Management concepts

Tenant KMS (BYOK) Overview

How it differs from Operator KMS

When to use it

Architecture

Key version states

Prerequisites

Quick start

Cache architecture

Sealed state