> ## 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.

# BYOK and KMS providers

> Wrap your tenant master key with a KMS key — operator-side or your own (BYOK). Revoke our access in one IAM change.

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](/essentials/key-management/tenant-master-key#sealed-state) on the next cache miss. The cache TTL bounds how long stale unwraps remain usable.

## Setup: AWS BYOK

<Note>
  For the full step-by-step setup guide including GCP and Azure, see the [Tenant KMS (BYOK) section](/essentials/tenant-kms/overview). This page covers the concepts and background; the Tenant KMS section has the operational runbooks.
</Note>

<Info>
  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.
</Info>

### 1. Create a KMS key in your AWS account

```bash theme={"dark"}
# 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:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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:

```bash theme={"dark"}
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:

1. Remove or detach the IAM policy that lets the assumed role call `kms:Decrypt` on your key.
2. Within the cache TTL (**5 minutes** for BYOK tenants), every tenant under this BYOK config will go sealed.
3. 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](/essentials/key-management/tenant-master-key#cryptographic-erasure-the-kill-switch)). The KMS key in your account is then irrelevant — the master key is gone.

## See also

* [Tenant master key →](/essentials/key-management/tenant-master-key)
* [Tenant KMS (BYOK) overview →](/essentials/tenant-kms/overview)