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.

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 isolationglobal (no setup)
KMS audit + hardware-backed wrapping, low ops burdenoperator_kms
Maximum sovereignty, kill-switch in your IAM, regulatory requirementcustomer_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 publishes <KNOXCALL_AWS_ACCOUNT_ID> in the admin UI under Settings → Security → Tenant KMS. 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 KMS → Add provider → 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 "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

ProviderStatusNotes
global✅ ShippedDefault; wraps with MASTER_KEY_B64.
operator_kms_aws✅ ShippedKnoxCall-managed AWS KMS key.
customer_kms_aws✅ ShippedBYOK in your AWS account. STS cross-account.
operator_kms_gcp✅ ShippedKnoxCall-managed GCP Cloud KMS key.
customer_kms_gcp✅ ShippedBYOK in your GCP project. Workload Identity Federation.
operator_kms_azure✅ ShippedKnoxCall-managed Azure Key Vault key.
customer_kms_azure✅ ShippedBYOK 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). The KMS key in your account is then irrelevant — the master key is gone.

​
See also