Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 within minutes.

​
How it differs from Operator KMS

There are three wrapping options:
Wrap methodWho holds the wrapping keyKill-switch location
globalKnoxCall (env var)None — contact support
operator_kmsKnoxCall-managed KMS keyNone — contact support
customer_kms (BYOK)Your AWS / GCP / Azure accountYour 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 session cache TTL, not the standard 1 hour. Agent sessions renew more frequently. Plan for this if you run long-lived self-hosted proxy deployments.

​
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 5 min)
Cache MISS → call customer KMS via IAM → unwrap master key → cache for 5 min
    ↓
Encrypt / decrypt with master key (local, fast)
This means one KMS round-trip per 5-minute window, not per request.

​
Key version states

StateMeaning
activeCurrent version. New wraps use this. One per tenant at a time.
retiredOlder version — still unwraps legacy ciphertext, no new wraps.
revokedCryptographic 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 token. 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://api.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 5 minutes for BYOK 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 5-minute 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