BYOK and KMS providers - KnoxCall Docs

By default, every KnoxCall tenant’s master key is wrapped with the deployment’s MASTER_KEY_B64 (the global wrap method). That gives you per-tenant cryptographic isolation, but the wrapping key is on the same compute as KnoxCall. If your security posture requires the wrapping key to live elsewhere — in a hardware-backed HSM, in a separate AWS account, or under your own IAM control — you opt into KMS-backed wrapping. Two flavours:

Operator KMS — KnoxCall manages a KMS key on your behalf (in our cloud account).
Customer KMS (BYOK) — the KMS key lives in your cloud account. You can revoke our access in one IAM change.

When to use each

If you want…	Pick
Default — minimal config, same crypto + per-tenant isolation	`global` (no setup)
KMS audit + hardware-backed wrapping, low ops burden	`operator_kms`
Maximum sovereignty, kill-switch in your IAM, regulatory requirement	`customer_kms` (BYOK)

If you don’t have a regulatory or sovereignty requirement, global is the right answer — it’s not weaker crypto, it’s just a different blast-radius story.

What gets wrapped vs encrypted directly

The tenant master key itself is wrapped by your KMS key.
Everything inside KnoxCall — secrets, DB admin passwords, CA private keys, transit-key versions — is encrypted with the tenant master key using AES-256-GCM, locally on KnoxCall’s compute.

KMS is in the path once per cache miss (default 1-hour TTL). It’s not in the path of every encrypt / decrypt, so your data ops aren’t gated on KMS latency or availability between cache flushes.

Operator KMS

KnoxCall operates a KMS key in our cloud account. Tenant master keys are wrapped with it. You don’t manage IAM, the key, or rotation — we do.

✅ Hardware-backed wrapping with KMS audit.
✅ Minimal config — pick the provider, we handle the rest.
⚠️ KnoxCall holds the wrapping key. Revoking access requires reaching out to us (or destroying the tenant entirely, which works because of cryptographic erasure).

Pick this if you want KMS-grade wrapping but don’t need a kill switch in your own cloud account.

Customer KMS (BYOK)

The wrapping key lives in your AWS / GCP / Azure account. KnoxCall is granted IAM permission to call Encrypt / Decrypt against that one key — nothing else.

✅ Strongest sovereignty: revoke our IAM grant and we can’t unwrap on the next cache miss.
✅ Your KMS audit log records every unwrap call we make.
✅ Required by some regulated buyers (FedRAMP, HIPAA, certain EU data-residency stories).
⚠️ You’re responsible for IAM, key rotation, and not breaking it during your own cloud changes.

When you “lock us out” by revoking the grant, every tenant whose master key is wrapped by that KMS key goes sealed on the next cache miss. The cache TTL bounds how long stale unwraps remain usable.

Setup: AWS BYOK

For the full step-by-step setup guide including GCP and Azure, see the Tenant KMS (BYOK) section. This page covers the concepts and background; the Tenant KMS section has the operational runbooks.

Customer KMS (BYOK) tenants have a 5-minute session cache TTL instead of the default 1 hour. Agent sessions renew more frequently — plan for this in self-hosted proxy deployments.

1. Create a KMS key in your AWS account

# In your AWS account, your region:
aws kms create-key \
  --description "KnoxCall tenant master key wrapping" \
  --key-usage ENCRYPT_DECRYPT \
  --key-spec SYMMETRIC_DEFAULT
# → Note the KeyId / Arn

2. Grant KnoxCall’s IAM principal access

KnoxCall assumes a role in your account via STS using a customer-supplied role_arn and external_id. Create a role with this trust policy in your account:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::<KNOXCALL_AWS_ACCOUNT_ID>:root" },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": { "sts:ExternalId": "<your-chosen-external-id>" }
    }
  }]
}

KnoxCall shows <KNOXCALL_AWS_ACCOUNT_ID> in the BYOK setup wizard (Settings → Security → Tenant Master Key → Customer KMS → Set up BYOK, AWS step) along with a ready-to-paste copy of this trust policy; it’s also returned by GET /admin/tenant-kms/provider-identity. The <your-chosen-external-id> is anything you generate (UUID is fine) — you’ll paste it into the admin UI. Attach this inline policy to the role, restricted to the one KMS key:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["kms:Encrypt", "kms:Decrypt"],
    "Resource": "<the-kms-key-arn>"
  }]
}

3. Configure the tenant in KnoxCall

In the admin UI: Settings → Security → Tenant Master Key → Customer KMS → Set up BYOK, select AWS KMS. Provide:

AWS region of the KMS key.
KMS key ARN (or alias ARN).
Role ARN of the role you created in step 2.
External ID matching the trust policy.

Or via API:

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

4. KnoxCall verifies the key

On save, KnoxCall does a probe encrypt + decrypt round-trip to prove the IAM grant works. The result lands in last_verified_at / last_verify_error on the config row. If verification fails, the change isn’t applied — you don’t end up with a half-broken config.

5. Provision the tenant master key under the new wrap

After verification succeeds, KnoxCall provisions a new tenant master key version wrapped with the KMS key. The new version becomes active; the previous (global-wrapped) version is retired. Existing data stays wrapped under the retired version until a rewrap migration runs. New writes use the new active version.

What credentials look like in the config

Per the schema, tenant_kms_config.config is non-secret configuration only — region, role_arn, external_id. Static credentials (AWS access keys, GCP service account JSON files, Azure client secrets) are rejected at the API level — not just discouraged. Cross-account access is always via STS-assumed roles for customer_kms. Operator KMS uses the deployment’s IAM role.

Provider support today

Provider	Status	Notes
`global`	✅ Shipped	Default; wraps with `MASTER_KEY_B64`.
`operator_kms_aws`	✅ Shipped	KnoxCall-managed AWS KMS key.
`customer_kms_aws`	✅ Shipped	BYOK in your AWS account. STS cross-account.
`operator_kms_gcp`	✅ Shipped	KnoxCall-managed GCP Cloud KMS key.
`customer_kms_gcp`	✅ Shipped	BYOK in your GCP project. Workload Identity Federation.
`operator_kms_azure`	✅ Shipped	KnoxCall-managed Azure Key Vault key.
`customer_kms_azure`	✅ Shipped	BYOK in your Azure subscription. Federated Credentials.

Revoking BYOK access (the kill switch)

If you ever need to lock KnoxCall out:

Remove or detach the IAM policy that lets the assumed role call kms:Decrypt on your key.
Within the cache TTL (5 minutes for BYOK tenants), every tenant under this BYOK config will go sealed.
New agent sessions fail; existing agents continue until their current session expires (at most 5 minutes).

To destroy the data instead of just freezing it: revoke the tenant master key itself in KnoxCall (cryptographic erasure — see tenant master key). The KMS key in your account is then irrelevant — the master key is gone.

​When to use each

​What gets wrapped vs encrypted directly

​Operator KMS

​Customer KMS (BYOK)

​Setup: AWS BYOK

​1. Create a KMS key in your AWS account

​2. Grant KnoxCall’s IAM principal access

​3. Configure the tenant in KnoxCall

​4. KnoxCall verifies the key

​5. Provision the tenant master key under the new wrap

​What credentials look like in the config

​Provider support today

​Revoking BYOK access (the kill switch)

​See also

When to use each

What gets wrapped vs encrypted directly

Operator KMS

Customer KMS (BYOK)

Setup: AWS BYOK

1. Create a KMS key in your AWS account

2. Grant KnoxCall’s IAM principal access

3. Configure the tenant in KnoxCall

4. KnoxCall verifies the key

5. Provision the tenant master key under the new wrap

What credentials look like in the config

Provider support today

Revoking BYOK access (the kill switch)

See also